[hooks] [code_assets] Library dartdoc comments

pkgs/code_assets/example/api/code_config_snippet.dart

@@ -0,0 +1,23 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+// ignore_for_file: unused_local_variable
+
+// snippet-start
+import 'package:code_assets/code_assets.dart';
+import 'package:hooks/hooks.dart';
+
+void main(List<String> args) async {
+  await build(args, (input, output) async {
+    if (input.config.buildCodeAssets) {
+      final codeConfig = input.config.code;
+      final targetOS = codeConfig.targetOS;
+      final targetArchitecture = codeConfig.targetArchitecture;
+
+      // Add some code assets.
+    }
+  });
+}
+
+// snippet-end

pkgs/code_assets/lib/code_assets.dart

@@ -2,15 +2,24 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
+/// @docImport 'package:hooks/hooks.dart';
 /// @docImport 'src/code_assets/code_asset.dart';
 /// @docImport 'src/code_assets/config.dart';
 
-/// Code asset support for hook authors.
+/// This package provides the API for code assets to be used with
+/// [`package:hooks`](https://pub.dev/packages/hooks).
+///
+/// A [CodeAsset] is an asset containing executable code which respects the
+/// native application binary interface (ABI). These assets are bundled with a
+/// Dart or Flutter application. They can be produced by compiling C, C++,
+/// Objective-C, Rust, or Go code for example.
 ///
-/// A code asset is an asset containing executable code which respects the
-/// native application binary interface (ABI).
+/// This package is used in a build hook (`hook/build.dart`) to inform the Dart
+/// and Flutter SDKs about the code assets that need to be bundled with an
+/// application.
 ///
-/// Code assets can be added in a build hook as follows:
+/// A [CodeAsset] can be added to the [BuildOutputBuilder] in a build hook as
+/// follows:
 ///
 /// <!-- file://./../example/api/code_assets_snippet.dart -->
 /// ```dart
@@ -34,13 +43,31 @@
 /// }
 /// ```
 ///
-/// See [CodeAsset] and [BuildOutputCodeAssetBuilder.add] for more details.
+/// The [CodeConfig] nested in the [HookInput] gives access to configuration
+/// specifically for compiling code assets. For example [CodeConfig.targetOS]
+/// and [CodeConfig.targetArchitecture] give access to the target OS and
+/// architecture that the code assets are compiled for:
 ///
-/// For more documentation of hooks, refer to the API docs of
-/// [`package:hooks`](https://pub.dev/packages/hooks).
+/// <!-- file://./../example/api/code_config_snippet.dart -->
+/// ```dart
+/// import 'package:code_assets/code_assets.dart';
+/// import 'package:hooks/hooks.dart';
+///
+/// void main(List<String> args) async {
+///   await build(args, (input, output) async {
+///     if (input.config.buildCodeAssets) {
+///       final codeConfig = input.config.code;
+///       final targetOS = codeConfig.targetOS;
+///       final targetArchitecture = codeConfig.targetArchitecture;
+///
+///       // Add some code assets.
+///     }
+///   });
+/// }
+/// ```
 ///
-/// When compiling C, C++ or Objective-C code from source, consider using
-/// [`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c).
+/// For more information about build hooks see
+/// [dart.dev/tools/hooks](https://dart.dev/tools/hooks).
 library;
 
 export 'src/code_assets/architecture.dart' show Architecture;

pkgs/hooks/lib/hooks.dart

@@ -4,10 +4,46 @@
 
 /// @docImport 'src/api/build_and_link.dart';
 
-/// A library that contains the protocol for implementing hooks.
+/// This package provides the API for hooks in Dart. Hooks are Dart scripts
+/// placed in the `hook/` directory of a Dart package, designed to automate
+/// tasks for a Dart package.
 ///
-/// The main entrypoint for build hooks (`hook/build.dart`) is [build]. The main
-/// entrypoint for link hooks (`hook/link.dart`) is [link].
+/// Currently, the main supported hook is the build hook (`hook/build.dart`).
+/// The build hook is executed during a Dart build and enables you to bundle
+/// assets with a Dart package. The main entrypoint for build hooks is [build].
+///
+/// The second hook available in this API is the link hook  (`hook/link.dart`).
+/// The main entrypoint for link hooks is [link].
+///
+/// Hooks can for example be used to bundle native code with a Dart package:
+///
+/// <!-- file://./../../code_assets/example/sqlite/hook/build.dart -->
+/// ```dart
+/// import 'package:code_assets/code_assets.dart';
+/// import 'package:hooks/hooks.dart';
+/// import 'package:native_toolchain_c/native_toolchain_c.dart';
+///
+/// void main(List<String> args) async {
+///   await build(args, (input, output) async {
+///     if (input.config.buildCodeAssets) {
+///       final builder = CBuilder.library(
+///         name: 'sqlite3',
+///         assetName: 'src/third_party/sqlite3.g.dart',
+///         sources: ['third_party/sqlite/sqlite3.c'],
+///         defines: {
+///           if (input.config.code.targetOS == OS.windows)
+///             // Ensure symbols are exported in dll.
+///             'SQLITE_API': '__declspec(dllexport)',
+///         },
+///       );
+///       await builder.run(input: input, output: output);
+///     }
+///   });
+/// }
+/// ```
+///
+/// For more information see
+/// [dart.dev/tools/hooks](https://dart.dev/tools/hooks).
 library;
 
 export 'src/api/build_and_link.dart' show build, link;