Merge branch 'main' into ffigen_lib_refactor

Author: liamappelbe

pkgs/code_assets/example/api/code_asset_snippet.dart

@@ -0,0 +1,18 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// 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.
+
+// dart format width=76
+
+// snippet-start
+import 'dart:ffi';
+
+void main() {
+  final result = add(14, 28);
+  print(result);
+}
+
+@Native<Int Function(Int, Int)>(assetId: 'package:my_package/add.dart')
+external int add(int a, int b);
+
+// snippet-end

pkgs/code_assets/example/api/code_assets_snippet.dart

@@ -0,0 +1,25 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// 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.
+
+// snippet-start
+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,
+      ),
+    );
+  });
+}
+
+// snippet-end

pkgs/code_assets/example/api/test_snippet.dart

@@ -0,0 +1,20 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// 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.
+
+// dart format width=76
+
+// snippet-start
+import 'package:code_assets/code_assets.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('test my build hook', () async {
+    await testCodeBuildHook(
+      mainMethod: (args) {},
+      check: (input, output) {},
+    );
+  });
+}
+
+// snippet-end

pkgs/code_assets/lib/code_assets.dart

@@ -12,6 +12,7 @@
 ///
 /// Code assets can be added in a build hook as follows:
 ///
+/// <!-- file://./../example/api/code_assets_snippet.dart -->
 /// ```dart
 /// import 'package:code_assets/code_assets.dart';
 /// import 'package:hooks/hooks.dart';

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

@@ -19,6 +19,7 @@ import 'syntax.g.dart';
 /// Native code assets can be accessed at runtime through native external
 /// functions via their asset [id]:
 ///
+/// <!-- file://./../../../example/api/code_asset_snippet.dart -->
 /// ```dart
 /// import 'dart:ffi';
 ///

pkgs/code_assets/lib/src/code_assets/testing.dart

@@ -21,12 +21,19 @@ import 'os.dart';
 ///
 /// This is intended to be used from tests, e.g.:
 ///
-/// ```
-/// test('test my build hook', () async {
-///   await testCodeBuildHook(
-///     ...
-///   );
-/// });
+/// <!-- file://./../../../example/api/test_snippet.dart -->
+/// ```dart
+/// import 'package:code_assets/code_assets.dart';
+/// import 'package:test/test.dart';
+///
+/// void main() {
+///   test('test my build hook', () async {
+///     await testCodeBuildHook(
+///       mainMethod: (args) {},
+///       check: (input, output) {},
+///     );
+///   });
+/// }
 /// ```
 ///
 /// The hook is run in isolation. No user-defines are read from the pubspec,

pkgs/data_assets/example/api/data_assets_snippet.dart

@@ -0,0 +1,22 @@
+// Copyright (c) 2025, the Dart project authors.  Please see the AUTHORS file
+// 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.
+
+// dart format width=76
+
+// snippet-start
+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),
+    );
+  });
+}
+
+// snippet-end

pkgs/data_assets/lib/data_assets.dart

@@ -12,6 +12,7 @@
 ///
 /// Data assets can be added in a build hook as follows:
 ///
+/// <!-- file://./../example/api/data_assets_snippet.dart -->
 /// ```dart
 /// import 'package:data_assets/data_assets.dart';
 /// import 'package:hooks/hooks.dart';
@@ -22,11 +23,7 @@
 ///     final assetPath = input.outputDirectory.resolve('...');
 ///
 ///     output.assets.data.add(
-///       DataAsset(
-///         package: packageName,
-///         name: '...',
-///         file: assetPath,
-///       ),
+///       DataAsset(package: packageName, name: '...', file: assetPath),
 ///     );
 ///   });
 /// }

pkgs/ffigen/test/large_integration_tests/large_objc_test.dart

@@ -39,8 +39,13 @@ void main() {
     bool randInclude(String kind, Declaration clazz, [String? method]) =>
         fnvHash32('$seed.$kind.${clazz.usr}.$method') <
         ((1 << 32) * inclusionRatio);
-    DeclarationFilters randomFilter(String kind) => DeclarationFilters(
-      shouldInclude: (Declaration clazz) => randInclude(kind, clazz),
+    DeclarationFilters randomFilter(
+      String kind, [
+      Set<String> forceIncludes = const {},
+    ]) => DeclarationFilters(
+      shouldInclude: (Declaration clazz) =>
+          forceIncludes.contains(clazz.originalName) ||
+          randInclude(kind, clazz),
       shouldIncludeMember: (Declaration clazz, String method) =>
           randInclude('$kind.memb', clazz, method),
     );
@@ -57,6 +62,10 @@ void main() {
       'large_integration_tests',
       'large_objc_bindings.m',
     );
+
+    // TODO(https://github.com/dart-lang/native/issues/2517): Remove this.
+    const forceIncludedProtocols = {'NSTextLocation'};
+
     final config = FfiGen(
       Logger.root,
       wrapperName: 'LargeObjCLibrary',
@@ -85,7 +94,7 @@ void main() {
       globals: randomFilter('globals'),
       typedefs: randomFilter('typedefs'),
       objcInterfaces: randomFilter('objcInterfaces'),
-      objcProtocols: randomFilter('objcProtocols'),
+      objcProtocols: randomFilter('objcProtocols', forceIncludedProtocols),
       objcCategories: randomFilter('objcCategories'),
       externalVersions: ExternalVersions(
         ios: Versions(min: Version(12, 0, 0)),

pkgs/hooks/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+## Dartdoc Comments Code Blocks
+
+Every code block must have a language.
+
+Every Dart code block must have an HTML comment pointing to its source.
+
+Correct:
+
+```
+    <!-- file://./CONTRIBUTING.md -->
+    ```dart
+    void main() {}
+    ```
+```
+
+```
+    ```yaml
+    foo: bar
+    ```
+```
+
+Incorrect:
+
+```
+    ```
+    void main() {}
+    ```
+```
+
+```
+    ```dart
+    void main() {}
+    ```
+```
+
+This is enforced by `pkgs/hooks/tool/update_snippets.dart`.