From 812ca6c11574a469e3ce44a359e0135b3f0283c8 Mon Sep 17 00:00:00 2001
From: Daco Harkes <dacoharkes@google.com>
Date: Tue, 14 Jan 2025 09:21:36 +0100
Subject: [PATCH 1/2] [native_assets_cli] [doc] Document multiple invocation
 behavior

---
 .../lib/src/code_assets/config.dart           |  9 +++++++
 pkgs/native_assets_cli/lib/src/config.dart    | 24 ++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/pkgs/native_assets_cli/lib/src/code_assets/config.dart b/pkgs/native_assets_cli/lib/src/code_assets/config.dart
index b6d5ddd66..998ddd132 100644
--- a/pkgs/native_assets_cli/lib/src/code_assets/config.dart
+++ b/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.
diff --git a/pkgs/native_assets_cli/lib/src/config.dart b/pkgs/native_assets_cli/lib/src/config.dart
index fcbd86eb9..35336a52f 100644
--- a/pkgs/native_assets_cli/lib/src/config.dart
+++ b/pkgs/native_assets_cli/lib/src/config.dart
@@ -611,10 +611,32 @@ 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:
+  ///
+  /// ```dart
+  /// if (input.config.buildAsstTypes.contains('some_asset_type')) {
+  ///   // Emit some asset.
+  /// }
+  /// ```
+  ///
+  /// Most asset extensions provide a shorthand. For example, `CodeAsset`s can
+  /// be used as follows:
+  ///
+  /// ```dart
+  /// if (input.config.buildCodeAssets) {
+  ///   // Emit code asset.
+  /// }
+  /// ```
   final List<String> buildAssetTypes;
 
   HookConfig(this.json)

From da7f8ebcd5e97c136bc041bfe29fc1a6ea2019d1 Mon Sep 17 00:00:00 2001
From: Daco Harkes <dacoharkes@google.com>
Date: Wed, 15 Jan 2025 20:23:43 +0100
Subject: [PATCH 2/2] address comment

---
 pkgs/native_assets_cli/lib/src/config.dart | 13 +++----------
 1 file changed, 3 insertions(+), 10 deletions(-)

diff --git a/pkgs/native_assets_cli/lib/src/config.dart b/pkgs/native_assets_cli/lib/src/config.dart
index 35336a52f..250163b55 100644
--- a/pkgs/native_assets_cli/lib/src/config.dart
+++ b/pkgs/native_assets_cli/lib/src/config.dart
@@ -621,16 +621,9 @@ final class HookConfig {
   /// 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:
-  ///
-  /// ```dart
-  /// if (input.config.buildAsstTypes.contains('some_asset_type')) {
-  ///   // Emit some asset.
-  /// }
-  /// ```
-  ///
-  /// Most asset extensions provide a shorthand. For example, `CodeAsset`s can
-  /// be used as follows:
+  /// 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) {