Skip to content

Commit c503ded

Browse files
authored
[record_use] Library documentation (dart-lang#3204)
1 parent 1c94455 commit c503ded

2 files changed

Lines changed: 97 additions & 2 deletions

File tree

‎pkgs/record_use/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ being recorded.
1111

1212
- If placed on a static method, the annotation means that arguments passed to
1313
the method will be recorded, as far as they can be inferred at compile time.
14-
- If placed on a class with a constant constructor, the annotation means that
15-
any constant instance of the class will be recorded.
14+
- If placed on a class, the annotation means that any constant instance of the
15+
class and any constructor invocation will be recorded.
1616

1717
> [!NOTE]
1818
> The `@RecordUse()` annotation is only allowed on definitions within a package's

‎pkgs/record_use/lib/record_use.dart‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,101 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5+
/// @docImport 'src/recordings.dart';
6+
7+
/// This package provides the data classes for the usage recording feature in
8+
/// the Dart SDK.
9+
///
10+
/// Dart objects with the `@RecordUse()` annotation are being recorded at
11+
/// compile time, providing the user with information. The information depends
12+
/// on the object being recorded.
13+
///
14+
/// The main entrypoint for recorded usages is [Recordings].
15+
///
16+
/// - If placed on a static method, the annotation means that arguments passed
17+
/// to the method will be recorded, as far as they can be inferred at compile
18+
/// time. These can be found in [Recordings.calls].
19+
/// - If placed on a class, the annotation means that any constant instance of
20+
/// the class and any constructor invocation will be recorded. These can be
21+
/// found in [Recordings.instances].
22+
///
23+
/// > [!NOTE]
24+
/// > The `@RecordUse()` annotation is only allowed on definitions within a
25+
/// > package's `lib/` directory. This includes definitions that are members of
26+
/// > a class, such as static methods.
27+
///
28+
/// ## Example
29+
///
30+
/// <!-- file://./../example/api/usage.dart#usage -->
31+
/// ```dart
32+
/// void main() {
33+
/// PirateTranslator.speak('Hello');
34+
/// print(const PirateShip('Black Pearl', 50));
35+
/// }
36+
///
37+
/// abstract class PirateTranslator {
38+
/// @RecordUse()
39+
/// static String speak(String english) => 'Ahoy $english';
40+
/// }
41+
///
42+
/// @RecordUse()
43+
/// final class PirateShip {
44+
/// final String name;
45+
/// final int cannons;
46+
///
47+
/// const PirateShip(this.name, this.cannons);
48+
/// }
49+
/// ```
50+
/// This code will generate a data file that contains both the field values of
51+
/// the `PirateShip` instances, as well as the arguments for the `speak`
52+
/// method annotated with `@RecordUse()`.
53+
///
54+
/// This information can then be accessed in a link hook as follows:
55+
/// <!-- file://./../example/api/usage_link.dart#link -->
56+
/// ```dart
57+
/// void main(List<String> arguments) {
58+
/// link(arguments, (input, output) async {
59+
/// final usesUri = input.recordedUsagesFile;
60+
/// if (usesUri == null) return;
61+
/// final usesJson = await File.fromUri(usesUri).readAsString();
62+
/// final uses = Recordings.fromJson(
63+
/// jsonDecode(usesJson) as Map<String, Object?>,
64+
/// );
65+
///
66+
/// final calls = uses.calls[methodId] ?? [];
67+
/// for (final call in calls) {
68+
/// switch (call) {
69+
/// case CallWithArguments(
70+
/// positionalArguments: [StringConstant(value: final english), ...],
71+
/// ):
72+
/// // Shrink a translations file based on all the different translation
73+
/// // keys.
74+
/// print('Translating to pirate: $english');
75+
/// case _:
76+
/// print('Cannot determine which translations are used.');
77+
/// }
78+
/// }
79+
///
80+
/// final ships = uses.instances[classId] ?? [];
81+
/// for (final ship in ships) {
82+
/// switch (ship) {
83+
/// case InstanceConstantReference(
84+
/// instanceConstant: InstanceConstant(
85+
/// fields: {'name': StringConstant(value: final name)},
86+
/// ),
87+
/// ):
88+
/// // Include the 3d model for this ship in the application but not
89+
/// // bundle the other ships.
90+
/// print('Pirate ship found: $name');
91+
/// case _:
92+
/// print('Cannot determine which ships are used.');
93+
/// }
94+
/// }
95+
/// });
96+
/// }
97+
/// ```
98+
library;
99+
5100
export 'src/constant.dart'
6101
show
7102
BoolConstant,

0 commit comments

Comments
 (0)