[dart2js] update documentation on resource identifiers.
Mainly small updates to the documentation to highlight how to use
it, but also warn about its current implementation status
Change-Id: I918711bd4127f170accf1cbf82e77aa2ff73d238
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/458070
Reviewed-by: Stephen Adams <sra@google.com>
Commit-Queue: Sigmund Cherem <sigmund@google.com>
diff --git a/pkg/compiler/doc/resource_identifiers.md b/pkg/compiler/doc/resource_identifiers.md
index e3e3dbc..6338700 100644
--- a/pkg/compiler/doc/resource_identifiers.md
+++ b/pkg/compiler/doc/resource_identifiers.md
@@ -1,24 +1,58 @@
# Resource Identifiers
-Content TBD. Work in progress and details in flux.
+Tree-shaking can cause APIs and resources to be removed from programs. We
+developed a mechanism in dart2js to help developers understand what resources
+are still in use after an application is optimized.
+
+## Status
+
+(experimental, in progress)
+
+Currently we have a mechanism that only supports tracking static member
+functions. It is not rich enough to track the use of resource classes or
+constants, like `IconData` in flutter applications. That would be an ideal
+expansion in the future.
+
+## How it works
+Today, a developer can tag a top-level method with two pragmas:
+```
+@pragma('dart2js:never-inline')
+@pragma('dart2js:resource-identifier')
+void myTopLevelMethod() {... }
+```
+
+This will indicate to dart2js that `myTopLevelMethod` is a member it needs to
+track. The `never-inline` pragma is necessary because dart2js cannot track
+members after they get inlined.
+
+When providing dart2js with the experimental `--write-resources` flag, the
+compiler will emit a `.resources.json` file. This file lists whether any
+top-level methods annotated with the special pragma was invoked in the program.
+It will also include some additional static information, like the source
+location of the call, or even which parameters where provided (if the parameters
+are constant).
### Example output
TODO: Reference goldens in tests rather than keep the example below.
-The call to `loadDeferredLibrary` in the Dart js_runtime is annotated with
+When compiling applications with deferred loading, the compiler emits a call to
+an internal `loadDeferredLibrary` in the Dart `js_runtime`. The
+`loadDeferredLibrary` method is annotated with
`@pragma('dart2js:resource-identifier')`. This means that an app that uses
-deferred loaded libraries will generate a section in the `.resources.json`.
+deferred loaded libraries will automatically generate a section in the
+`.resources.json`.
-
-In the Dart sdk directory, compile:
+In the Dart sdk directory, there is a sample benchmark that contains deferred
+loaded libraries. If you compile it as:
```sh
dart compile js --write-resources --out=somedir/o.js \
benchmarks/OmnibusDeferred/dart/OmnibusDeferred.dart
```
-`somedir/o.js.resource_identifiers.json`:
+You can inspect `somedir/o.js.resource_identifiers.json` to see what the output
+looks like. At the time this doc was written, the output was:
```json
{
