[native_assets_cli] [doc] Add READMEs for examples (#1878)

Add READMEs for the current set of supported use cases.

I added a cross-link to the transformer test case so it doubles as example.

Closes: #1375

pkgs/native_assets_builder/test_data/transformer/README.md

@@ -0,0 +1,17 @@
+An example of a library that transforms some source files and bundles them as
+data assets.
+
+## Usage
+
+Data assets are not yet consumable in Dart and Flutter.
+This package is for illustration purposes only.
+
+## Code organization
+
+A typical layout of a package with data assets:
+
+* `data/` contains source files.
+* `hook/build.dart` loops over all these files and transforms them. It reports
+  the transformed files as data assets. The file transformations are cached
+  within the hook to prevent retransforming the files if the sources didn't
+  change.

pkgs/native_assets_cli/example/build/README.md

@@ -1,9 +1,38 @@
-The examples in this folder illustrate how native code is built and bundled
-in Dart and Flutter apps.
-
-* [native_add_app/](native_add_app/) has a dependency with C code.
-  This app should declare nothing special. Dart and Flutter should check
-  all dependencies for native code.
-* [native_add_library/](native_add_library/) contains a library with C code.
-  When Dart code in this library or dependent on this library is invoked, the
-  C code must be built and bundled so that it can be used by the Dart code.
+The examples in this folder illustrate how assets are built and bundled in Dart
+and Flutter apps.
+
+Currently two main asset types are supported in `package:native_assets_cli`:
+  * Native libraries
+  * Data assets
+
+Note that Data assets are not yet consumable in Dart and Flutter.
+
+Examples:
+
+* Bundling C/C++/Objective-C source code in a package. This native code is built on the developers' machine when such package is a dependency.
+  * [native_add_library/](native_add_library/) contains a library with C code.
+    When Dart code in this library or dependent on this library is invoked, the
+    C code must be built and bundled so that it can be used by the Dart code.
+  * [native_add_app/](native_add_app/) has a dependency with C code.
+    This app should declare nothing special. Dart and Flutter should check
+    all dependencies for native code.
+* Bundling prebuilt native libaries.
+  * [download_asset/](download_asset/) is very similar to
+    [native_add_library/](native_add_library/), but instead of building the
+    native code on the machine of developers pulling in the package, the native
+    libraries are prebuilt in GitHub actions and downloaded in the build hook.
+* Bundling multiple dynamic libraries depending on each other.
+  * [native_dynamic_linking/](native_dynamic_linking/) contains source code for
+    3 native libraries that depend on each other and load each other with the
+    native dynamic loader at runtime.
+* Building dynamic libraries against `dart_api_dl.h`.
+  * [use_dart_api/](use_dart_api/) contains a library with C code that invokes
+    `dart_api_dl.h` to interact with the Dart runtime.
+* Bundling all files in a directory as data assets.
+  * [local_asset/](local_asset/) contains a package that bundles all files in
+    the `assets/` directory as data assets.
+* Transforming files and bundling them as data assets.
+  * [transformer/](../../../native_assets_builder/test_data/transformer/README.md)
+    contains a package that transforms files and bundles the result as data
+    assets. The hook uses caching internally to prevent retransforming files if
+    not needed.

pkgs/native_assets_cli/example/build/local_asset/README.md

@@ -1,5 +1,13 @@
-This example shows two use cases:
+An example of a library bundling all files in a directory as data assets.
 
-* Data assets that are part of the package source code.
-* Code assets which are downloaded from the cloud.
-  (It doesn't show how to download, but shows how to implement the protocol correctly.)
+## Usage
+
+Data assets are not yet consumable in Dart and Flutter.
+This package is for illustration purposes only.
+
+## Code organization
+
+A typical layout of a package with data assets:
+
+* `assets/` contains data assets.
+* `hook/build.dart` reports all these files as data assets.