[hooks] [code_assets] Add lint public_member_api_docs (#2353)

Author: dcharkes

pkgs/code_assets/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.19.4
+
+* Add doc comments to all public members.
+
 ## 0.19.3
 
 * Mark this package as in preview.

pkgs/code_assets/analysis_options.yaml

@@ -14,6 +14,7 @@ linter:
   rules:
     - avoid_positional_boolean_parameters
     - dangling_library_doc_comments
+    - public_member_api_docs
     - prefer_const_declarations
     - prefer_expression_function_bodies
     - prefer_final_in_for_each

pkgs/code_assets/lib/src/code_assets/architecture.dart

@@ -88,6 +88,7 @@ final class Architecture {
   static final Architecture current = _abiToArch[Abi.current()]!;
 }
 
+/// Extension methods for [Architecture] to convert to and from the syntax.
 extension ArchitectureSyntaxExtension on Architecture {
   static final _toSyntax = {
     for (final item in Architecture.values)
@@ -98,8 +99,10 @@ extension ArchitectureSyntaxExtension on Architecture {
     for (var entry in _toSyntax.entries) entry.value: entry.key,
   };
 
+  /// Converts this [Architecture] to its corresponding [ArchitectureSyntax].
   ArchitectureSyntax toSyntax() => _toSyntax[this]!;
 
+  /// Converts an [ArchitectureSyntax] to its corresponding [Architecture].
   static Architecture fromSyntax(ArchitectureSyntax syntax) =>
       switch (_fromSyntax[syntax]) {
         null => throw FormatException(

pkgs/code_assets/lib/src/code_assets/c_compiler_config.dart

@@ -73,8 +73,10 @@ final class CCompilerConfig {
 /// The configuration provided in [CCompilerConfig.windows] when
 /// [CodeConfig.targetOS] is [OS.windows].
 final class WindowsCCompilerConfig {
+  /// The configuration for the Windows Developer Command Prompt.
   final DeveloperCommandPrompt? developerCommandPrompt;
 
+  /// Constructs a new [WindowsCCompilerConfig].
   WindowsCCompilerConfig({this.developerCommandPrompt});
 }
 
@@ -107,17 +109,23 @@ final class DeveloperCommandPrompt {
   /// script name does not.
   final List<String> arguments;
 
+  /// Constructs a new [DeveloperCommandPrompt].
   DeveloperCommandPrompt({required this.script, required this.arguments});
 }
 
+/// Extension methods for [CCompilerConfig] to convert to and from the syntax
+/// model.
 extension CCompilerConfigSyntaxExtension on CCompilerConfig {
+  /// Converts this [CCompilerConfig] to its corresponding
+  /// [CCompilerConfigSyntax].
   CCompilerConfigSyntax toSyntax() => CCompilerConfigSyntax(
     ar: archiver,
     cc: compiler,
     ld: linker,
     windows: _windows?.toSyntax(),
   );
 
+  /// Converts a [CCompilerConfigSyntax] to its corresponding [CCompilerConfig].
   static CCompilerConfig fromSyntax(CCompilerConfigSyntax cCompiler) =>
       CCompilerConfig(
         archiver: cCompiler.ar,
@@ -132,10 +140,15 @@ extension CCompilerConfigSyntaxExtension on CCompilerConfig {
       );
 }
 
+/// Extension methods for [WindowsCCompilerConfig] to convert to and from the
+/// syntax model.
 extension WindowsCCompilerConfigSyntaxExtension on WindowsCCompilerConfig {
+  /// Converts this [WindowsCCompilerConfig] to its corresponding
+  /// [WindowsSyntax].
   WindowsSyntax toSyntax() =>
       WindowsSyntax(developerCommandPrompt: developerCommandPrompt?.toSyntax());
 
+  /// Converts a [WindowsSyntax] to its corresponding [WindowsCCompilerConfig].
   static WindowsCCompilerConfig fromSyntax(WindowsSyntax windows) =>
       WindowsCCompilerConfig(
         developerCommandPrompt: switch (windows.developerCommandPrompt) {
@@ -145,10 +158,16 @@ extension WindowsCCompilerConfigSyntaxExtension on WindowsCCompilerConfig {
       );
 }
 
+/// Extension methods for [DeveloperCommandPrompt] to convert to and from the
+/// syntax model.
 extension DeveloperCommandPromptSyntaxExtension on DeveloperCommandPrompt {
+  /// Converts this [DeveloperCommandPrompt] to its corresponding
+  /// [DeveloperCommandPromptSyntax].
   DeveloperCommandPromptSyntax toSyntax() =>
       DeveloperCommandPromptSyntax(script: script, arguments: arguments);
 
+  /// Converts a [DeveloperCommandPromptSyntax] to its corresponding
+  /// [DeveloperCommandPrompt].
   static DeveloperCommandPrompt fromSyntax(DeveloperCommandPromptSyntax dcp) =>
       DeveloperCommandPrompt(script: dcp.script, arguments: dcp.arguments);
 }

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

@@ -84,6 +84,7 @@ final class CodeAsset {
 
   CodeAsset._({required this.id, required this.linkMode, required this.file});
 
+  /// Creates a [CodeAsset] from an [EncodedAsset].
   factory CodeAsset.fromEncoded(EncodedAsset asset) {
     assert(asset.isCodeAsset);
     final syntaxNode = NativeCodeAssetEncodingSyntax.fromJson(
@@ -97,6 +98,7 @@ final class CodeAsset {
     );
   }
 
+  /// Creates a copy of this [CodeAsset] with the given fields replaced.
   CodeAsset copyWith({LinkMode? linkMode, String? id, Uri? file}) =>
       CodeAsset._(
         id: id ?? this.id,
@@ -115,6 +117,7 @@ final class CodeAsset {
   @override
   int get hashCode => Object.hash(id, linkMode, file);
 
+  /// Encodes this [CodeAsset] into an [EncodedAsset].
   EncodedAsset encode() {
     final encoding = NativeCodeAssetEncodingSyntax(
       file: file,
@@ -125,16 +128,22 @@ final class CodeAsset {
   }
 }
 
+/// Extension for identifying the type of a [CodeAsset].
 extension CodeAssetType on CodeAsset {
+  /// The type identifier for [CodeAsset]s in a hook input or output.
   static const String type = NativeCodeAssetNewSyntax.typeValue;
 }
 
 /// Methods on [EncodedAsset] for [CodeAsset]s.
 extension EncodedCodeAsset on EncodedAsset {
+  /// Whether this [EncodedAsset] represents a [CodeAsset].
   bool get isCodeAsset => type == CodeAssetType.type;
+
+  /// Converts this [EncodedAsset] to a [CodeAsset].
   CodeAsset get asCodeAsset => CodeAsset.fromEncoded(this);
 }
 
+/// Provides OS-specific library naming conventions.
 extension OSLibraryNaming on OS {
   /// The default dynamic library file name on this os.
   String dylibFileName(String name) {

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

@@ -18,25 +18,29 @@ extension HookConfigCodeConfig on HookConfig {
   /// Code asset specific configuration.
   CodeConfig get code => CodeConfig._fromJson(json, path);
 
+  /// Whether the hook invoker (e.g. the Dart or Flutter SDK) expects this
+  /// hook to build code assets.
   bool get buildCodeAssets => buildAssetTypes.contains(CodeAssetType.type);
 }
 
 /// Extension to the [LinkInput] providing access to configuration specific to
 /// code assets as well as code asset inputs to the linker (only available if
 /// code assets are supported).
 extension LinkInputCodeAssets on LinkInputAssets {
-  // Returns the code assets that were sent to this linker.
-  //
-  // NOTE: If the linker implementation depends on the contents of the files the
-  // code assets refer (e.g. looks at static archives and links them) then the
-  // linker script has to add those files as dependencies via
-  // [LinkOutput.addDependency] to ensure the linker script will be re-run if
-  // the content of the files changes.
+  /// The [CodeAsset]s in this [LinkInputAssets.encodedAssets].
+  ///
+  /// NOTE: If the linker implementation depends on the contents of the files
+  /// the code assets refer (e.g. looks at static archives and links them) then
+  /// the linker script has to add those files as dependencies via
+  /// [HookOutputBuilder.addDependencies] to ensure the linker script will be
+  /// re-run if the content of the files changes.
   Iterable<CodeAsset> get code =>
       encodedAssets.where((e) => e.isCodeAsset).map(CodeAsset.fromEncoded);
 }
 
 /// The configuration for [CodeAsset]s in [HookConfig].
+///
+/// Available via [HookConfigCodeConfig.code].
 final class CodeConfig {
   final CodeConfigSyntax _syntax;
 
@@ -53,6 +57,7 @@ final class CodeConfig {
   Architecture get targetArchitecture =>
       ArchitectureSyntaxExtension.fromSyntax(_syntax.targetArchitecture);
 
+  /// The preferred link for [CodeAsset]s.
   LinkModePreference get linkModePreference =>
       LinkModePreferenceSyntaxExtension.fromSyntax(_syntax.linkModePreference);
 
@@ -101,6 +106,7 @@ final class IOSCodeConfig {
   /// The lowest iOS version that the compiled code will be compatible with.
   int get targetVersion => _syntax.targetVersion;
 
+  /// Constructs a new [IOSCodeConfig].
   IOSCodeConfig({required IOSSdk targetSdk, required int targetVersion})
     : _syntax = IOSCodeConfigSyntax(
         targetSdk: targetSdk.type,
@@ -119,6 +125,7 @@ final class AndroidCodeConfig {
   /// compatible with.
   int get targetNdkApi => _syntax.targetNdkApi;
 
+  /// Constructs a new [AndroidCodeConfig].
   AndroidCodeConfig({required int targetNdkApi})
     : _syntax = AndroidCodeConfigSyntax(targetNdkApi: targetNdkApi);
 }
@@ -133,6 +140,7 @@ final class MacOSCodeConfig {
   /// The lowest MacOS version that the compiled code will be compatible with.
   int get targetVersion => _syntax.targetVersion;
 
+  /// Constructs a new [MacOSCodeConfig].
   MacOSCodeConfig({required int targetVersion})
     : _syntax = MacOSCodeConfigSyntax(targetVersion: targetVersion);
 }
@@ -145,6 +153,7 @@ extension BuildOutputAssetsBuilderCode on BuildOutputAssetsBuilder {
 
 /// Extension on [BuildOutputBuilder] to add [CodeAsset]s.
 final class BuildOutputCodeAssetBuilder {
+  /// Provides access to emitting code assets.
   final BuildOutputAssetsBuilder _output;
 
   BuildOutputCodeAssetBuilder._(this._output);
@@ -185,6 +194,8 @@ final class LinkOutputCodeAssetBuilder {
 
 /// Extension to initialize code specific configuration on link/build inputs.
 extension CodeAssetBuildInputBuilder on HookConfigBuilder {
+  /// Sets up the code asset specific configuration for a build or link hook
+  /// input.
   void setupCode({
     required Architecture targetArchitecture,
     required OS targetOS,
@@ -229,19 +240,30 @@ extension LinkOutputCodeAssets on LinkOutputAssets {
       .toList();
 }
 
+/// Extension methods for [MacOSCodeConfig] to convert to and from the syntax
+/// model.
 extension MacOSCodeConfigSyntaxExtension on MacOSCodeConfig {
+  /// Converts this [MacOSCodeConfig] to its corresponding
+  /// [MacOSCodeConfigSyntax].
   MacOSCodeConfigSyntax toSyntax() =>
       MacOSCodeConfigSyntax(targetVersion: targetVersion);
 }
 
+/// Extension methods for [IOSCodeConfig] to convert to and from the syntax
+/// model.
 extension IOSCodeConfigSyntaxExtension on IOSCodeConfig {
+  /// Converts this [IOSCodeConfig] to its corresponding [IOSCodeConfigSyntax].
   IOSCodeConfigSyntax toSyntax() => IOSCodeConfigSyntax(
     targetSdk: targetSdk.type,
     targetVersion: targetVersion,
   );
 }
 
+/// Extension methods for [AndroidCodeConfig] to convert to and from the syntax
+/// model.
 extension AndroidCodeConfigSyntaxExtension on AndroidCodeConfig {
+  /// Converts this [AndroidCodeConfig] to its corresponding
+  /// [AndroidCodeConfigSyntax].
   AndroidCodeConfigSyntax toSyntax() =>
       AndroidCodeConfigSyntax(targetNdkApi: targetNdkApi);
 }

pkgs/code_assets/lib/src/code_assets/extension.dart

@@ -15,14 +15,34 @@ import 'validation.dart';
 /// The protocol extension for the `hook/build.dart` and `hook/link.dart`
 /// with [CodeAsset]s and [CodeConfig].
 final class CodeAssetExtension implements ProtocolExtension {
+  /// The architecture to build for.
   final Architecture targetArchitecture;
+
+  /// The operating system to build for.
   final OS targetOS;
+
+  /// The preferred link mode.
   final LinkModePreference linkModePreference;
+
+  /// Optional C compiler configuration.
   final CCompilerConfig? cCompiler;
+
+  /// Optional Android specific configuration.
+  ///
+  /// Required if [targetOS] is [OS.android].
   final AndroidCodeConfig? android;
+
+  /// Optional iOS specific configuration.
+  ///
+  /// Required if [targetOS] is [OS.iOS].
   final IOSCodeConfig? iOS;
+
+  /// Optional macOS specific configuration.
+  ///
+  /// Required if [targetOS] is [OS.macOS].
   final MacOSCodeConfig? macOS;
 
+  /// Constructs a [CodeAssetExtension].
   CodeAssetExtension({
     required this.targetArchitecture,
     required this.targetOS,

pkgs/code_assets/lib/src/code_assets/ios_sdk.dart

@@ -6,6 +6,9 @@ import 'config.dart';
 
 /// The iOS SDK (device or simulator) in [IOSCodeConfig.targetSdk].
 final class IOSSdk {
+  /// The type of this [IOSSdk].
+  ///
+  /// A string such as `iphoneos` or `iphonesimulator`.
   final String type;
 
   const IOSSdk._(this.type);

pkgs/code_assets/lib/src/code_assets/link_mode.dart

@@ -34,7 +34,10 @@ abstract final class LinkMode {
   Map<String, Object?> toJson() => toSyntax().json;
 }
 
+/// Extension methods for [LinkMode] to convert to and from the syntax model.
 extension LinkModeSyntaxExtension on LinkMode {
+  /// Converts this [LinkMode] to its corresponding [LinkModeSyntax]
+  /// representation.
   LinkModeSyntax toSyntax() => switch (this) {
     StaticLinking() => StaticLinkModeSyntax(),
     LookupInProcess() => DynamicLoadingProcessLinkModeSyntax(),
@@ -46,6 +49,8 @@ extension LinkModeSyntaxExtension on LinkMode {
     _ => throw UnimplementedError('The link mode "$this" is not known'),
   };
 
+  /// Converts a [LinkModeSyntax] to its corresponding [LinkMode]
+  /// representation.
   static LinkMode fromSyntax(LinkModeSyntax linkMode) => switch (linkMode) {
     _ when linkMode.isStaticLinkMode => StaticLinking(),
     _ when linkMode.isDynamicLoadingProcessLinkMode => LookupInProcess(),
@@ -86,6 +91,7 @@ final class DynamicLoadingBundled extends DynamicLoading {
 
   static final DynamicLoadingBundled _singleton = DynamicLoadingBundled._();
 
+  /// Returns the singleton instance of [DynamicLoadingBundled].
   factory DynamicLoadingBundled() => _singleton;
 
   @override
@@ -100,9 +106,10 @@ final class DynamicLoadingBundled extends DynamicLoading {
 /// At runtime, the dynamic library will be loaded and the symbols will be
 /// looked up in this dynamic library.
 final class DynamicLoadingSystem extends DynamicLoading {
-  /// The [Uri] of the
+  /// The [Uri] of the dynamic library on the system.
   final Uri uri;
 
+  /// Constructs a [DynamicLoadingSystem] with the given [uri].
   DynamicLoadingSystem(this.uri) : super._();
 
   static const _typeValue = 'dynamic_loading_system';
@@ -127,6 +134,7 @@ final class LookupInProcess extends DynamicLoading {
 
   static final LookupInProcess _singleton = LookupInProcess._();
 
+  /// Returns the singleton instance of [LookupInProcess].
   factory LookupInProcess() => _singleton;
 
   @override
@@ -142,6 +150,7 @@ final class LookupInExecutable extends DynamicLoading {
 
   static final LookupInExecutable _singleton = LookupInExecutable._();
 
+  /// Returns the singleton instance of [LookupInExecutable].
   factory LookupInExecutable() => _singleton;
 
   @override
@@ -160,6 +169,8 @@ final class LookupInExecutable extends DynamicLoading {
 // TODO(https://github.com/dart-lang/sdk/issues/49418): Support static linking.
 final class StaticLinking extends LinkMode {
   const StaticLinking._() : super._();
+
+  /// Returns the singleton instance of [StaticLinking].
   factory StaticLinking() => _singleton;
 
   static const StaticLinking _singleton = StaticLinking._();