[hooks] [code_assets] [data_assets] Library documentation and readme (#2479)

This PR adds code snippets and cross links to the library documentation and readmes.

(Once dart-lang/site-www#6759 is merged, we can also add links to the hooks page.)

Author: dcharkes

pkgs/code_assets/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.19.6-wip
+
+- Added a library comment detailing how to use the package.
+
 ## 0.19.5
 
 - Bump `package:hooks` to 0.20.0.

pkgs/code_assets/README.md

@@ -6,6 +6,38 @@
 A library to use in build hooks (`hook/build.dart`) for building and bundling
 code assets.
 
+A code asset is an asset containing executable code which respects the native
+application binary interface (ABI).
+
+Code assets can be added in a build hook as follows:
+
+```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 {
+    final packageName = input.packageName;
+    final assetPath = input.outputDirectory.resolve('...');
+
+    output.assets.code.add(
+      CodeAsset(
+        package: packageName,
+        name: '...',
+        linkMode: DynamicLoadingBundled(),
+        file: assetPath,
+      ),
+    );
+  });
+}
+```
+
+For more documentation of hooks, refer to the API docs of
+[`package:hooks`](https://pub.dev/packages/hooks).
+
+When compiling C, C++ or Objective-C code from source, consider using
+[`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c).
+
 ## Status: In Preview
 
 **NOTE**: This package is currently in preview and published under the

pkgs/code_assets/lib/code_assets.dart

@@ -2,7 +2,44 @@
 // 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 'src/code_assets/code_asset.dart';
+/// @docImport 'src/code_assets/config.dart';
+
 /// Code asset support for hook authors.
+///
+/// A code asset is an asset containing executable code which respects the
+/// native application binary interface (ABI).
+///
+/// Code assets can be added in a build hook as follows:
+///
+/// ```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 {
+///     final packageName = input.packageName;
+///     final assetPath = input.outputDirectory.resolve('...');
+///
+///     output.assets.code.add(
+///       CodeAsset(
+///         package: packageName,
+///         name: '...',
+///         linkMode: DynamicLoadingBundled(),
+///         file: assetPath,
+///       ),
+///     );
+///   });
+/// }
+/// ```
+///
+/// See [CodeAsset] and [BuildOutputCodeAssetBuilder.add] for more details.
+///
+/// For more documentation of hooks, refer to the API docs of
+/// [`package:hooks`](https://pub.dev/packages/hooks).
+///
+/// When compiling C, C++ or Objective-C code from source, consider using
+/// [`package:native_toolchain_c`](https://pub.dev/packages/native_toolchain_c).
 library;
 
 export 'src/code_assets/architecture.dart' show Architecture;

pkgs/code_assets/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   This library contains the hook protocol specification for bundling native code
   with Dart packages.
 
-version: 0.19.5
+version: 0.19.6-wip
 
 repository: https://github.com/dart-lang/native/tree/main/pkgs/code_assets
 
@@ -21,7 +21,7 @@ environment:
 
 dependencies:
   collection: ^1.19.1
-  hooks: ^0.20.0
+  hooks: ^0.20.1-wip
 
 dev_dependencies:
   custom_lint: ^0.7.5

pkgs/data_assets/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.19.3-wip
+
+- Added a library comment detailing how to use the package.
+
 ## 0.19.2
 
 - Bump `package:hooks` to 0.20.0.

pkgs/data_assets/README.md

@@ -6,6 +6,34 @@
 A library to use in build hooks (`hook/build.dart`) for building and bundling
 data assets.
 
+A data asset is an asset bundled as data (String or bytes) with a Dart or
+Flutter application.
+
+Data assets can be added in a build hook as follows:
+
+```dart
+import 'package:data_assets/data_assets.dart';
+import 'package:hooks/hooks.dart';
+///
+void main(List<String> args) async {
+  await build(args, (input, output) async {
+    final packageName = input.packageName;
+    final assetPath = input.outputDirectory.resolve('...');
+
+    output.assets.data.add(
+      DataAsset(
+        package: packageName,
+        name: '...',
+        file: assetPath,
+      ),
+    );
+  });
+}
+```
+
+For more documentation of hooks, refer to the API docs of
+[`package:hooks`](https://pub.dev/packages/hooks).
+
 ## Status: Experimental
 
 **NOTE**: This package is currently experimental and published under the

pkgs/data_assets/lib/data_assets.dart

@@ -2,7 +2,40 @@
 // 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 'src/data_assets/config.dart';
+/// @docImport 'src/data_assets/data_asset.dart';
+
 /// Data asset support for hook authors.
+///
+/// A data asset is an asset bundled as data (String or bytes) with a Dart or
+/// Flutter application.
+///
+/// Data assets can be added in a build hook as follows:
+///
+/// ```dart
+/// import 'package:data_assets/data_assets.dart';
+/// import 'package:hooks/hooks.dart';
+///
+/// void main(List<String> args) async {
+///   await build(args, (input, output) async {
+///     final packageName = input.packageName;
+///     final assetPath = input.outputDirectory.resolve('...');
+///
+///     output.assets.data.add(
+///       DataAsset(
+///         package: packageName,
+///         name: '...',
+///         file: assetPath,
+///       ),
+///     );
+///   });
+/// }
+/// ```
+///
+/// See [DataAsset] and [BuildOutputDataAssetsBuilder.add] for more details.
+///
+/// For more documentation of hooks, refer to the API docs of
+/// [`package:hooks`](https://pub.dev/packages/hooks).
 library;
 
 export 'src/data_assets/config.dart'

pkgs/data_assets/pubspec.yaml

@@ -3,7 +3,7 @@ description: >-
   This library contains the hook protocol specification for bundling data assets
   with Dart packages.
 
-version: 0.19.2
+version: 0.19.3-wip
 
 repository: https://github.com/dart-lang/native/tree/main/pkgs/data_assets
 
@@ -17,7 +17,7 @@ environment:
   sdk: '>=3.9.0-21.0.dev <4.0.0'
 
 dependencies:
-  hooks: ^0.20.0
+  hooks: ^0.20.1-wip
 
 dev_dependencies:
   custom_lint: ^0.7.5

pkgs/hooks/CHANGELOG.md

@@ -1,21 +1,25 @@
+## 0.20.1-wip
+
+- Update outdated documentation.
+
 ## 0.20.0
 
-* **Breaking change**  Rename `EncodedAsset.jsonPath` to
+- **Breaking change**  Rename `EncodedAsset.jsonPath` to
   `EncodedAsset.encodingJsonPath`. This field only governs the `EncodedAsset.encoding` field, not the whole object.
-* Enable passing metadata from link hooks of a package to the link hooks in 
+- Enable passing metadata from link hooks of a package to the link hooks in 
   dependencies, by fixing the link hook execution order.
 
 ## 0.19.5
 
-* Stop leaking unexported symbols.
+- Stop leaking unexported symbols.
 
 ## 0.19.4
 
-* Add doc comments to all public members.
+- Add doc comments to all public members.
 
 ## 0.19.3
 
-* Mark this package as in preview.
+- Mark this package as in preview.
 
 ## 0.19.1
 

pkgs/hooks/README.md

@@ -5,6 +5,9 @@
 
 A library to use in build hooks (`hook/build.dart`).
 
+For more documentation on adding native code to your package, refer to the API
+docs of [`package:code_assets`](https://pub.dev/packages/code_assets).
+
 ## Status: In Preview
 
 **NOTE**: This package is currently in preview and published under the