[rfw] Add some more documentation for RFW (#4349)

Author: Hixie

packages/rfw/CHANGELOG.md

@@ -1,6 +1,11 @@
+## 1.0.11
+
+* Adds more documentation in the README.md file!
+* Adds automated verification of the sample code in the README.
+
 ## 1.0.10
 
-* Fixes stale ignore: prefer_const_constructors.
+* Fixes stale ignore: `prefer_const_constructors`.
 * Updates minimum supported SDK version to Flutter 3.10/Dart 3.0.
 * Changes package internals to avoid explicit `as Uint8List` downcast.
 

packages/rfw/README.md

@@ -16,6 +16,10 @@ void main() {
   runApp(const Example());
 }
 
+// The "#docregion" comment helps us keep this code in sync with the
+// excerpt in the rfw package's README.md file.
+//
+// #docregion Example
 class Example extends StatefulWidget {
   const Example({super.key});
 
@@ -54,8 +58,11 @@ class _ExampleState extends State<Example> {
   @override
   void initState() {
     super.initState();
+    // Local widget library:
     _runtime.update(coreName, createCoreWidgets());
+    // Remote widget library:
     _runtime.update(mainName, _remoteWidgets);
+    // Configuration data:
     _data.update('greet', <String, Object>{'name': 'World'});
   }
 
@@ -73,3 +80,4 @@ class _ExampleState extends State<Example> {
     );
   }
 }
+// #enddocregion Example

packages/rfw/example/hello/lib/main.dart

@@ -16,6 +16,10 @@ void main() {
   runApp(const Example());
 }
 
+// The "#docregion" comment helps us keep this code in sync with the
+// excerpt in the rfw package's README.md file.
+//
+// #docregion Example
 class Example extends StatefulWidget {
   const Example({super.key});
 
@@ -35,6 +39,9 @@ class _ExampleState extends State<Example> {
 
   @override
   void reassemble() {
+    // This function causes the Runtime to be updated any time the app is
+    // hot reloaded, so that changes to _createLocalWidgets can be seen
+    // during development. This function has no effect in production.
     super.reassemble();
     _update();
   }
@@ -87,3 +94,4 @@ class _ExampleState extends State<Example> {
     );
   }
 }
+// #enddocregion Example

packages/rfw/example/local/lib/main.dart

@@ -25,7 +25,12 @@ widget CalculatorPad = Column(
   children: [
     Row(
       children: [
+        // The "#docregion" pragma here allows us to inline this as an example
+        // in the "rfw" package's README.md file. It is unrelated to what this
+        // example is otherwise trying to show and can be disregarded.
+        // #docregion button7
         CalculatorButton(label: "7", onPressed: event "digit" { arguments: [7] }),
+        // #enddocregion button7
         CalculatorButton(label: "8", onPressed: event "digit" { arguments: [8] }),
         CalculatorButton(label: "9", onPressed: event "digit" { arguments: [9] }),
         SizedBox(width: 116.0, height: 116.0),
@@ -58,6 +63,7 @@ widget CalculatorPad = Column(
   ],
 );
 
+// #docregion CalculatorButton
 widget CalculatorButton = Padding(
   padding: [8.0],
   child: SizedBox(
@@ -69,7 +75,9 @@ widget CalculatorButton = Padding(
     ),
   ),
 );
+// #enddocregion CalculatorButton
 
+// #docregion Button
 widget Button { down: false } = GestureDetector(
   onTap: args.onPressed,
   onTapDown: set state.down = true,
@@ -110,6 +118,7 @@ widget Button { down: false } = GestureDetector(
     ),
   ),
 );
+// #enddocregion Button
 
 widget Display = Container(
   height: 80.0,

packages/rfw/example/wasm/logic/calculator.rfwtxt

@@ -533,7 +533,7 @@ DynamicMap parseDataFile(String file) {
 /// event "..." { }
 /// ```
 ///
-/// Tthe string is the name of the event, and the arguments map is the data to
+/// The string is the name of the event, and the arguments map is the data to
 /// send with the event.
 ///
 /// For example, the event handler in the following sequence sends the event

packages/rfw/lib/src/dart/text.dart

@@ -537,6 +537,8 @@ Map<String, LocalWidgetBuilder> get _coreWidgetsDefinitions => <String, LocalWid
     );
   },
 
+  // The "#docregion" pragma below makes this accessible from the README.md file.
+  // #docregion Row
   'Row': (BuildContext context, DataSource source) {
     return Row(
       mainAxisAlignment: ArgumentDecoders.enumValue<MainAxisAlignment>(MainAxisAlignment.values, source, ['mainAxisAlignment']) ?? MainAxisAlignment.start,
@@ -548,6 +550,7 @@ Map<String, LocalWidgetBuilder> get _coreWidgetsDefinitions => <String, LocalWid
       children: source.childList(['children']),
     );
   },
+  // #enddocregion Row
 
   'SafeArea': (BuildContext context, DataSource source) {
     return SafeArea(

packages/rfw/lib/src/flutter/core_widgets.dart

@@ -2,7 +2,7 @@ name: rfw
 description: "Remote Flutter widgets: a library for rendering declarative widget description files at runtime."
 repository: https://github.com/flutter/packages/tree/main/packages/rfw
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+rfw%22
-version: 1.0.10
+version: 1.0.11
 
 environment:
   sdk: ">=3.0.0 <4.0.0"