[native_assets_cli] [doc] Document multiple invocation behavior (#1891)

Document the behavior of multiple invocations of hooks.

Closes: #1739

We could keep `buildAssetTypes` as a list of strings for now. We might want to make link hooks work with multiple asset types later as a non-breaking change.

Both Dart and Flutter only pass `[CodeAsset.type]`, so they are already satisfying that every asset type has its own invocation.

Author: dcharkes

pkgs/native_assets_cli/lib/src/code_assets/config.dart

@@ -41,6 +41,8 @@ class CodeConfig {
   final Architecture? _targetArchitecture;
 
   final LinkModePreference linkModePreference;
+
+  /// A compiler toolchain able to target [targetOS] with [targetArchitecture].
   final CCompilerConfig? cCompiler;
 
   /// The operating system being compiled for.
@@ -106,6 +108,13 @@ class CodeConfig {
     );
   }
 
+  /// The architecture the code code asset should be built for.
+  ///
+  /// The build and link hooks are invoked once per [targetArchitecture]. If the
+  /// invoker produces multi-architecture applications, the invoker is
+  /// responsible for combining the [CodeAsset]s for individual architectures
+  /// into a universal binary. So, the build and link hook implementations are
+  /// not responsible for providing universal binaries.
   Architecture get targetArchitecture {
     // TODO: Remove once Dart 3.7 stable is out and we bump the minimum SDK to
     // 3.7.

pkgs/native_assets_cli/lib/src/config.dart

@@ -611,10 +611,25 @@ final latestVersion = Version(1, 8, 0);
 /// catches issues with 2.)
 final latestParsableVersion = Version(1, 5, 0);
 
+/// The configuration for a build or link hook invocation.
 final class HookConfig {
   final Map<String, Object?> json;
 
-  /// The asset types that the invoker of this hook supports.
+  /// The asset types that should be built by an invocation of a hook.
+  ///
+  /// The invoker of a hook may, and in most cases will, invoke the hook
+  /// separately for different asset types.
+  ///
+  /// This means that hooks should be written in a way that they are a no-op if
+  /// they are invoked for an asset type that is not emitted by the hook. Most
+  /// asset extensions provide a to check [buildAssetTypes] for their own asset
+  /// type. For example, `CodeAsset`s can be used as follows:
+  ///
+  /// ```dart
+  /// if (input.config.buildCodeAssets) {
+  ///   // Emit code asset.
+  /// }
+  /// ```
   final List<String> buildAssetTypes;
 
   HookConfig(this.json)