[native_assets_cli] Document exit code behavior (#1762)

Closes: #33

The behavior is already tested by pkgs/native_assets_builder/test/build_runner/build_runner_build_output_format_test.dart.

Author: dcharkes

pkgs/native_assets_cli/lib/src/api/build.dart

@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets build.
 ///
+/// Meant to be used in build hooks (`hook/build.dart`).
+///
 /// Can build native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -87,6 +89,11 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+///
+/// If the [builder] fails, it must `throw`. Build hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> build(
   List<String> arguments,
   Future<void> Function(BuildConfig config, BuildOutputBuilder output) builder,

pkgs/native_assets_cli/lib/src/api/link.dart

@@ -11,6 +11,8 @@ import '../validation.dart';
 
 /// Runs a native assets link.
 ///
+/// Meant to be used in link hooks (`hook/link.dart`).
+///
 /// Can link native assets which are not already available, or expose existing
 /// files. Each individual asset is assigned a unique asset ID.
 ///
@@ -30,6 +32,10 @@ import '../validation.dart';
 ///   });
 /// }
 /// ```
+/// If the [linker] fails, it must `throw`. Link hooks are guaranteed to be
+/// invoked with a process invocation and should return a non-zero exit code on
+/// failure. Throwing will lead to an uncaught exception, causing a non-zero
+/// exit code.
 Future<void> link(
   List<String> arguments,
   Future<void> Function(LinkConfig config, LinkOutputBuilder output) linker,