[code_assets] Document asset namespacing (#2734)

Author: dcharkes

pkgs/code_assets/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 0.19.10
 
 - Document `input.packageRoot` in more places.
+- Document `CodeAsset.id` package namespacing.
 
 ## 0.19.9
 

pkgs/code_assets/lib/src/code_assets/code_asset.dart

@@ -53,6 +53,11 @@ import 'syntax.g.dart';
 /// specified location on the current system into the application bundle.
 final class CodeAsset {
   /// The id of this code asset.
+  ///
+  /// The identifier is a uri `package:<package>/<name>`. In build hooks,
+  /// `<package>` must be the name of the package containing the build hook.
+  /// Code assets are name-spaced in their own package to avoid naming
+  /// conflicts.
   final String id;
 
   /// The link mode for this native code.
@@ -71,18 +76,23 @@ final class CodeAsset {
   ///
   /// If the [linkMode] is [LookupInProcess], or [LookupInExecutable] the file
   /// must be omitted in the [BuildOutput].
+  ///
+  /// Code assets with [DynamicLoadingBundled] may not have conflicting file
+  /// names, the dynamic linker treats them as a single namespace.
   final Uri? file;
 
   /// Constructs a native code asset.
   ///
   /// The [id] of this asset is a uri `package:<package>/<name>` from [package]
-  /// and [name].
+  /// and [name]. In build hooks, [package] must be the name of the package
+  /// containing the build hook. Code assets are name-spaced in their own
+  /// package to avoid naming conflicts.
   CodeAsset({
     required String package,
     required String name,
-    required LinkMode linkMode,
-    Uri? file,
-  }) : this._(id: 'package:$package/$name', linkMode: linkMode, file: file);
+    required this.linkMode,
+    this.file,
+  }) : id = 'package:$package/$name';
 
   CodeAsset._({required this.id, required this.linkMode, required this.file});
 

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

@@ -169,6 +169,10 @@ final class BuildOutputCodeAssetBuilder {
   /// The [CodeAsset.file], if provided, must be an absolute path. Prefer
   /// constructing the path via [HookInput.outputDirectoryShared] or
   /// [HookInput.outputDirectory].
+  ///
+  /// The [CodeAsset.id] must be starting with `package:<package>/` where
+  /// `<package>` is the package name of the build hook where this method is
+  /// called.
   void add(CodeAsset asset, {AssetRouting routing = const ToAppBundle()}) =>
       _output.addEncodedAsset(asset.encode(), routing: routing);
 
@@ -177,6 +181,10 @@ final class BuildOutputCodeAssetBuilder {
   /// The [CodeAsset.file]s, if provided, must be absolute paths. Prefer
   /// constructing the paths via [HookInput.outputDirectoryShared] or
   /// [HookInput.outputDirectory].
+  ///
+  /// The [CodeAsset.id]s must be starting with `package:<package>/` where
+  /// `<package>` is the package name of the build hook where this method is
+  /// called.
   void addAll(
     Iterable<CodeAsset> assets, {
     AssetRouting routing = const ToAppBundle(),