Analyze sample code (#10619)

dev/bots/analyze-sample-code.dart

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:path/path.dart' as path;
+
+final String _flutterRoot = path.dirname(path.dirname(path.dirname(path.fromUri(Platform.script))));
+final String _flutter = path.join(_flutterRoot, 'bin', Platform.isWindows ? 'flutter.bat' : 'flutter');
+
+class Line {
+  const Line(this.filename, this.line, this.indent);
+  final String filename;
+  final int line;
+  final int indent;
+  Line get next => this + 1;
+  Line operator +(int count) {
+    if (count == 0)
+      return this;
+    return new Line(filename, line + count, indent);
+  }
+  @override
+  String toString([int column]) {
+    if (column != null)
+      return '$filename:$line:${column + indent}';
+    return '$filename:$line';
+  }
+}
+
+class Section {
+  const Section(this.start, this.preamble, this.code, this.postamble);
+  final Line start;
+  final String preamble;
+  final List<String> code;
+  final String postamble;
+  Iterable<String> get strings sync* {
+    if (preamble != null)
+      yield preamble;
+    yield* code;
+    if (postamble != null)
+      yield postamble;
+  }
+  List<Line> get lines {
+    final List<Line> result = new List<Line>.generate(code.length, (int index) => start + index);
+    if (preamble != null)
+      result.insert(0, null);
+    if (postamble != null)
+      result.add(null);
+    return result;
+  }
+}
+
+const String kDartDocPrefix = '///';
+const String kDartDocPrefixWithSpace = '$kDartDocPrefix ';
+
+/// To run this: bin/cache/dart-sdk/bin/dart dev/bots/analyze-sample-code.dart
+Future<Null> main() async {
+  final Directory temp = Directory.systemTemp.createTempSync('analyze_sample_code_');
+  int exitCode = 1;
+  bool keepMain = false;
+  try {
+    final File mainDart = new File(path.join(temp.path, 'main.dart'));
+    final File pubSpec = new File(path.join(temp.path, 'pubspec.yaml'));
+    final Directory flutterPackage = new Directory(path.join(_flutterRoot, 'packages', 'flutter', 'lib'));
+    final List<Section> sections = <Section>[];
+    int sampleCodeSections = 0;
+    for (FileSystemEntity file in flutterPackage.listSync(recursive: true, followLinks: false)) {
+      if (file is File && path.extension(file.path) == '.dart') {
+        final List<String> lines = file.readAsLinesSync();
+        bool inPreamble = false;
+        bool inSampleSection = false;
+        bool inDart = false;
+        bool foundDart = false;
+        int lineNumber = 0;
+        final List<String> block = <String>[];
+        Line startLine;
+        for (String line in lines) {
+          lineNumber += 1;
+          final String trimmedLine = line.trim();
+          if (inPreamble) {
+            if (line.isEmpty) {
+              inPreamble = false;
+              processBlock(startLine, block, sections);
+            } else if (!line.startsWith('// ')) {
+              throw '${file.path}:$lineNumber: Unexpected content in sample code preamble.';
+            } else {
+              block.add(line.substring(3));
+            }
+          } else if (inSampleSection) {
+            if (!trimmedLine.startsWith(kDartDocPrefix) || trimmedLine.startsWith('/// ##')) {
+              if (inDart)
+                throw '${file.path}:$lineNumber: Dart section inexplicably unterminated.';
+              if (!foundDart)
+                throw '${file.path}:$lineNumber: No dart block found in sample code section';
+              inSampleSection = false;
+            } else {
+              if (inDart) {
+                if (trimmedLine == '/// ```') {
+                  inDart = false;
+                  processBlock(startLine, block, sections);
+                } else if (trimmedLine == kDartDocPrefix) {
+                  block.add('');
+                } else {
+                  final int index = line.indexOf(kDartDocPrefixWithSpace);
+                  if (index < 0)
+                    throw '${file.path}:$lineNumber: Dart section inexplicably did not contain "$kDartDocPrefixWithSpace" prefix.';
+                  block.add(line.substring(index + 4));
+                }
+              } else if (trimmedLine == '/// ```dart') {
+                assert(block.isEmpty);
+                startLine = new Line(file.path, lineNumber + 1, line.indexOf(kDartDocPrefixWithSpace) + kDartDocPrefixWithSpace.length);
+                inDart = true;
+                foundDart = true;
+              }
+            }
+          } else if (line == '// Examples can assume:') {
+            assert(block.isEmpty);
+            startLine = new Line(file.path, lineNumber + 1, 3);
+            inPreamble = true;
+          } else if (trimmedLine == '/// ## Sample code') {
+            inSampleSection = true;
+            foundDart = false;
+            sampleCodeSections += 1;
+          }
+        }
+      }
+    }
+    final List<String> buffer = <String>[];
+    buffer.add('// generated code');
+    buffer.add('import \'dart:math\' as math;');
+    buffer.add('import \'dart:ui\' as ui;');
+    for (FileSystemEntity file in flutterPackage.listSync(recursive: false, followLinks: false)) {
+      if (file is File && path.extension(file.path) == '.dart') {
+        buffer.add('');
+        buffer.add('// ${file.path}');
+        buffer.add('import \'package:flutter/${path.basename(file.path)}\';');
+      }
+    }
+    buffer.add('');
+    final List<Line> lines = new List<Line>.filled(buffer.length, null, growable: true);
+    for (Section section in sections) {
+      buffer.addAll(section.strings);
+      lines.addAll(section.lines);
+    }
+    mainDart.writeAsStringSync(buffer.join('\n'));
+    pubSpec.writeAsStringSync('''
+name: analyze_sample_code
+dependencies:
+  flutter:
+    sdk: flutter
+''');
+    print('Found $sampleCodeSections sample code sections.');
+    final Process process = await Process.start(
+      _flutter,
+      <String>['analyze', '--no-preamble', mainDart.path],
+      workingDirectory: temp.path,
+    );
+    stderr.addStream(process.stderr);
+    final List<String> errors = await process.stdout.transform<String>(UTF8.decoder).transform<String>(const LineSplitter()).toList();
+    if (errors.first.startsWith('Running "flutter packages get" in '))
+      errors.removeAt(0);
+    if (errors.first.startsWith('Analyzing '))
+      errors.removeAt(0);
+    if (errors.last.endsWith(' issues found.') || errors.last.endsWith(' issue found.'))
+      errors.removeLast();
+    int errorCount = 0;
+    for (String error in errors) {
+      const String kBullet = ' • ';
+      const String kAt = ' at main.dart:';
+      const String kColon = ':';
+      final int start = error.indexOf(kBullet);
+      final int end = error.indexOf(kAt);
+      if (start >= 0 && end >= 0) {
+        final String message = error.substring(start + kBullet.length, end);
+        final int colon2 = error.indexOf(kColon, end + kAt.length);
+        if (colon2 < 0)
+          throw 'failed to parse error message: $error';
+        final String line = error.substring(end + kAt.length, colon2);
+        final int bullet2 = error.indexOf(kBullet, colon2);
+        if (bullet2 < 0)
+          throw 'failed to parse error message: $error';
+        final String column = error.substring(colon2 + kColon.length, bullet2);
+        final int lineNumber = int.parse(line, radix: 10, onError: (String source) => throw 'failed to parse error message: $error');
+        final int columnNumber = int.parse(column, radix: 10, onError: (String source) => throw 'failed to parse error message: $error');
+        if (lineNumber < 0 || lineNumber >= lines.length)
+          throw 'failed to parse error message: $error';
+        final Line actualLine = lines[lineNumber - 1];
+        final String errorCode = error.substring(bullet2 + kBullet.length);
+        if (errorCode == 'unused_element') {
+          // We don't really care if sample code isn't used!
+        } else if (actualLine == null) {
+          if (errorCode == 'missing_identifier' && lineNumber > 1 && buffer[lineNumber - 2].endsWith(',')) {
+            final Line actualLine = lines[lineNumber - 2];
+            print('${actualLine.toString(buffer[lineNumber - 2].length - 1)}: unexpected comma at end of sample code');
+            errorCount += 1;
+          } else {
+            print('${mainDart.path}:${lineNumber - 1}:$columnNumber: $message');
+            keepMain = true;
+            errorCount += 1;
+          }
+        } else {
+          print('${actualLine.toString(columnNumber)}: $message ($errorCode)');
+          errorCount += 1;
+        }
+      } else {
+        print('?? $error');
+        errorCount += 1;
+      }
+    }
+    exitCode = await process.exitCode;
+    if (exitCode == 1 && errorCount == 0)
+      exitCode = 0;
+    if (exitCode == 0)
+      print('No errors!');
+  } finally {
+    if (keepMain) {
+      print('Kept ${temp.path} because it had errors (see above).');
+    } else {
+      temp.deleteSync(recursive: true);
+    }
+  }
+  exit(exitCode);
+}
+
+int _expressionId = 0;
+
+void processBlock(Line line, List<String> block, List<Section> sections) {
+  if (block.isEmpty)
+    throw '$line: Empty ```dart block in sample code.';
+  if (block.first.startsWith('new ') || block.first.startsWith('const ')) {
+    _expressionId += 1;
+    sections.add(new Section(line, 'dynamic expression$_expressionId = ', block.toList(), ';'));
+  } else if (block.first.startsWith('class ') || block.first.startsWith('const ')) {
+    sections.add(new Section(line, null, block.toList(), null));
+  } else {
+    final List<String> buffer = <String>[];
+    int subblocks = 0;
+    Line subline;
+    for (int index = 0; index < block.length; index += 1) {
+      if (block[index] == '' || block[index] == '// ...') {
+        if (subline == null)
+          throw '${line + index}: Unexpected blank line or "// ..." line near start of subblock in sample code.';
+        subblocks += 1;
+        processBlock(subline, buffer, sections);
+        assert(buffer.isEmpty);
+        subline = null;
+      } else if (block[index].startsWith('// ')) {
+        if (buffer.length > 1) // don't include leading comments
+          buffer.add('/${block[index]}'); // so that it doesn't start with "// " and get caught in this again
+      } else {
+        subline ??= line + index;
+        buffer.add(block[index]);
+      }
+    }
+    if (subblocks > 0) {
+      if (subline != null)
+        processBlock(subline, buffer, sections);
+    } else {
+      sections.add(new Section(line, null, block.toList(), null));
+    }
+  }
+  block.clear();
+}

dev/bots/test.dart

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
 import 'dart:async';
 import 'dart:convert';
 import 'dart:io';
@@ -37,6 +41,11 @@ Future<Null> main() async {
       options: <String>['--flutter-repo'],
     );
 
+    // Analyze all the sample code in the repo
+    await _runCommand(dart, <String>[path.join(flutterRoot, 'dev', 'bots', 'analyze-sample-code.dart')],
+      workingDirectory: flutterRoot,
+    );
+
     // Try with the --watch analyzer, to make sure it returns success also.
     // The --benchmark argument exits after one run.
     await _runFlutterAnalyze(flutterRoot,

examples/flutter_gallery/lib/demo/cupertino/cupertino_buttons_demo.dart

@@ -5,8 +5,6 @@
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
-const Color _kBlue = const Color(0xFF007AFF);
-
 class CupertinoButtonsDemo extends StatefulWidget {
   static const String routeName = '/cupertino/buttons';
 
@@ -27,15 +25,17 @@ class _CupertinoButtonDemoState extends State<CupertinoButtonsDemo> {
         children: <Widget> [
           const Padding(
             padding: const EdgeInsets.all(16.0),
-            child: const Text('iOS themed buttons are flat. They can have borders or backgrounds but '
-                'only when necessary.'),
+            child: const Text(
+              'iOS themed buttons are flat. They can have borders or backgrounds but '
+              'only when necessary.'
+            ),
           ),
           new Expanded(
             child: new Column(
               mainAxisAlignment: MainAxisAlignment.center,
               children: <Widget> [
                 new Text(_pressedCount > 0
-                    ? 'Button pressed $_pressedCount time${_pressedCount == 1 ? '' : 's'}'
+                    ? 'Button pressed $_pressedCount time${_pressedCount == 1 ? "" : "s"}'
                     : ' '),
                 const Padding(padding: const EdgeInsets.all(12.0)),
                 new Align(
@@ -46,7 +46,7 @@ class _CupertinoButtonDemoState extends State<CupertinoButtonsDemo> {
                       new CupertinoButton(
                         child: const Text('Cupertino Button'),
                         onPressed: () {
-                          setState(() {_pressedCount++;});
+                          setState(() { _pressedCount += 1; });
                         }
                       ),
                       const CupertinoButton(
@@ -59,15 +59,15 @@ class _CupertinoButtonDemoState extends State<CupertinoButtonsDemo> {
                 const Padding(padding: const EdgeInsets.all(12.0)),
                 new CupertinoButton(
                   child: const Text('With Background'),
-                  color: _kBlue,
+                  color: CupertinoColors.activeBlue,
                   onPressed: () {
-                    setState(() {_pressedCount++;});
+                    setState(() { _pressedCount += 1; });
                   }
                 ),
                 const Padding(padding: const EdgeInsets.all(12.0)),
                 const CupertinoButton(
                   child: const Text('Disabled'),
-                  color: _kBlue,
+                  color: CupertinoColors.activeBlue,
                   onPressed: null,
                 ),
               ],

examples/flutter_gallery/lib/demo/cupertino/cupertino_dialog_demo.dart

@@ -5,8 +5,6 @@
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
-const Color _kBlue = const Color(0xFF007AFF);
-
 class CupertinoDialogDemo extends StatefulWidget {
   static const String routeName = '/cupertino/dialog';
 
@@ -44,7 +42,7 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
         children: <Widget> [
           new CupertinoButton(
             child: const Text('Alert'),
-            color: _kBlue,
+            color: CupertinoColors.activeBlue,
             onPressed: () {
               showDemoDialog<String>(
                 context: context,
@@ -69,7 +67,7 @@ class _CupertinoDialogDemoState extends State<CupertinoDialogDemo> {
           const Padding(padding: const EdgeInsets.all(8.0)),
           new CupertinoButton(
             child: const Text('Alert with Title'),
-            color: _kBlue,
+            color: CupertinoColors.activeBlue,
             padding: const EdgeInsets.symmetric(vertical: 16.0, horizontal: 36.0),
             onPressed: () {
               showDemoDialog<String>(

packages/flutter/lib/foundation.dart

@@ -16,6 +16,15 @@ export 'package:meta/meta.dart' show
   protected,
   required;
 
+// Examples can assume:
+// bool _first;
+// bool _lights;
+// bool _visible;
+// double _volume;
+// dynamic _selection;
+// dynamic _last;
+// dynamic _calculation;
+
 export 'src/foundation/assertions.dart';
 export 'src/foundation/basic_types.dart';
 export 'src/foundation/binding.dart';

packages/flutter/lib/src/animation/animation_controller.dart

@@ -15,6 +15,9 @@ import 'listener_helpers.dart';
 
 export 'package:flutter/scheduler.dart' show TickerFuture, TickerCanceled;
 
+// Examples can assume:
+// AnimationController _controller;
+
 /// The direction in which an animation is running.
 enum _AnimationDirection {
   /// The animation is running from beginning to end.
@@ -44,17 +47,20 @@ const Tolerance _kFlingTolerance = const Tolerance(
 /// * Define the [upperBound] and [lowerBound] values of an animation.
 /// * Create a [fling] animation effect using a physics simulation.
 ///
-/// By default, an [AnimationController] linearly produces values that range from 0.0 to 1.0, during
-/// a given duration. The animation controller generates a new value whenever the device running
-/// your app is ready to display a new frame (typically, this rate is around 60 values per second).
+/// By default, an [AnimationController] linearly produces values that range
+/// from 0.0 to 1.0, during a given duration. The animation controller generates
+/// a new value whenever the device running your app is ready to display a new
+/// frame (typically, this rate is around 60 values per second).
 ///
-/// An AnimationController needs a [TickerProvider], which is configured using the `vsync` argument
-/// on the constructor. If you are creating an AnimationController from a [State], then you can use
-/// the [TickerProviderStateMixin] and [SingleTickerProviderStateMixin] classes to obtain a suitable
-/// [TickerProvider]. The widget test framework [WidgetTester] object can be used as a ticker provider
-/// in the context of tests. In other contexts, you will have to either pass a [TickerProvider] from
-/// a higher level (e.g. indirectly from a [State] that mixes in [TickerProviderStateMixin]), or
-/// create a custom [TickerProvider] subclass.
+/// An AnimationController needs a [TickerProvider], which is configured using
+/// the `vsync` argument on the constructor. If you are creating an
+/// AnimationController from a [State], then you can use the
+/// [TickerProviderStateMixin] and [SingleTickerProviderStateMixin] classes to
+/// obtain a suitable [TickerProvider]. The widget test framework [WidgetTester]
+/// object can be used as a ticker provider in the context of tests. In other
+/// contexts, you will have to either pass a [TickerProvider] from a higher
+/// level (e.g. indirectly from a [State] that mixes in
+/// [TickerProviderStateMixin]), or create a custom [TickerProvider] subclass.
 ///
 /// The methods that start animations return a [TickerFuture] object which
 /// completes when the animation completes successfully, and never throws an

packages/flutter/lib/src/animation/tween.dart

@@ -97,7 +97,7 @@ class _ChainedEvaluation<T> extends Animatable<T> {
 /// `_animation`:
 ///
 /// ```dart
-/// _animation = new Tween<Offset>(
+/// Animation<Offset> _animation = new Tween<Offset>(
 ///   begin: const Offset(100.0, 50.0),
 ///   end: const Offset(200.0, 300.0),
 /// ).animate(_controller);

packages/flutter/lib/src/cupertino/colors.dart

@@ -4,7 +4,8 @@
 
 import 'dart:ui' show Color;
 
-/// [Color] constants that describe colors commonly used in iOS applications.
+/// A palette of [Color] constants that describe colors commonly used when
+/// matching the iOS platform aesthetics.
 class CupertinoColors {
   CupertinoColors._();
 
@@ -18,9 +19,18 @@ class CupertinoColors {
   static const Color activeGreen = const Color(0xFF4CD964);
 
   /// Opaque white color. Used for backgrounds and fonts against dark backgrounds.
+  ///
+  /// See also:
+  ///
+  ///  * [Colors.white], the same color, in the material design palette.
+  ///  * [black], opaque black in the [CupertinoColors] palette.
   static const Color white = const Color(0xFFFFFFFF);
 
   /// Opaque black color. Used for texts against light backgrounds.
+  ///
+  /// See also:
+  ///
+  ///  * [Colors.black], the same color, in the material design palette.
   static const Color black = const Color(0xFF000000);
 
   /// Used in iOS 10 for light background fills such as the chat bubble background.

packages/flutter/lib/src/cupertino/switch.dart

@@ -22,8 +22,28 @@ import 'thumb_painter.dart';
 /// that use a switch will listen for the [onChanged] callback and rebuild the
 /// switch with a new [value] to update the visual appearance of the switch.
 ///
+/// ## Sample code
+///
+/// This sample shows how to use a [CupertinoSwitch] in a [ListTile]. The
+/// [MergeSemantics] is used to turn the entire [ListTile] into a single item
+/// for accessibility tools.
+///
+/// ```dart
+/// new MergeSemantics(
+///   child: new ListTile(
+///     title: new Text('Lights'),
+///     trailing: new CupertinoSwitch(
+///       value: _lights,
+///       onChanged: (bool value) { setState(() { _lights = value; }); },
+///     ),
+///     onTap: () { setState(() { _lights = !_lights; }); },
+///   ),
+/// )
+/// ```
+///
 /// See also:
 ///
+///  * [Switch], the material design equivalent.
 ///  * <https://developer.apple.com/ios/human-interface-guidelines/ui-controls/switches/>
 class CupertinoSwitch extends StatefulWidget {
   /// Creates an iOS-style switch.

packages/flutter/lib/src/material/app_bar.dart

@@ -21,6 +21,11 @@ import 'tabs.dart';
 import 'theme.dart';
 import 'typography.dart';
 
+// Examples can assume:
+// void _airDress() { }
+// void _restitchDress() { }
+// void _repairDress() { }
+
 const double _kLeadingWidth = kToolbarHeight; // So the leading button is square.
 
 // Bottom justify the kToolbarHeight child which may overflow the top.

packages/flutter/lib/src/material/circle_avatar.dart

@@ -9,6 +9,9 @@ import 'constants.dart';
 import 'theme.dart';
 import 'typography.dart';
 
+// Examples can assume:
+// String userAvatarUrl;
+
 /// A circle that represents a user.
 ///
 /// Typically used with a user's profile image, or, in the absence of

packages/flutter/lib/src/material/colors.dart

@@ -105,7 +105,7 @@ class MaterialAccentColor extends ColorSwatch<int> {
 /// using an integer for the specific color desired, as follows:
 ///
 /// ```dart
-/// Colors.green[400]  // Selects a mid-range green.
+/// Color selection = Colors.green[400]; // Selects a mid-range green.
 /// ```
 ///
 /// Each [ColorSwatch] constant is a color and can used directly. For example:
@@ -369,9 +369,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.red[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -412,9 +412,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.redAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -449,9 +449,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.pink[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -492,9 +492,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.pinkAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -529,9 +529,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.purple[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -572,9 +572,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.purpleAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -609,9 +609,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.deepPurple[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -652,9 +652,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.deepPurpleAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -689,9 +689,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.indigo[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -732,9 +732,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.indigoAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -771,9 +771,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.blue[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -814,9 +814,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.blueAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -851,9 +851,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.lightBlue[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -894,9 +894,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.lightBlueAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -933,9 +933,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.cyan[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -976,9 +976,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.cyanAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1013,9 +1013,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.teal[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1056,9 +1056,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.tealAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1096,9 +1096,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.green[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1142,9 +1142,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.greenAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1179,9 +1179,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.lightGreen[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1222,9 +1222,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.lightGreenAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1259,9 +1259,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.lime[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1302,9 +1302,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.limeAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1339,9 +1339,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.yellow[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1382,9 +1382,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.yellowAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1419,9 +1419,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.amber[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1462,9 +1462,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.amberAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1501,9 +1501,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.orange[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1544,9 +1544,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.orangeAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1583,9 +1583,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.deepOrange[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1626,9 +1626,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.deepOrangeAccent[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1662,9 +1662,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.brown[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1708,9 +1708,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.grey[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:
@@ -1755,9 +1755,9 @@ class Colors {
   ///
   /// ```dart
   /// new Icon(
-  ///    icon: Icons.widgets,
+  ///   Icons.widgets,
   ///   color: Colors.blueGrey[400],
-  ///  ),
+  /// )
   /// ```
   ///
   /// See also:

packages/flutter/lib/src/material/popup_menu.dart

@@ -16,6 +16,10 @@ import 'list_tile.dart';
 import 'material.dart';
 import 'theme.dart';
 
+// Examples can assume:
+// enum Commands { heroAndScholar, hurricaneCame }
+// dynamic _heroAndScholar;
+
 const Duration _kMenuDuration = const Duration(milliseconds: 300);
 const double _kBaselineOffsetFromBottom = 20.0;
 const double _kMenuCloseIntervalEnd = 2.0 / 3.0;
@@ -133,7 +137,7 @@ class _PopupMenuDividerState extends State<PopupMenuDivider> {
 /// const PopupMenuItem<WhyFarther>(
 ///   value: WhyFarther.harder,
 ///   child: const Text('Working a lot harder'),
-/// ),
+/// )
 /// ```
 ///
 /// See the example at [PopupMenuButton] for how this example could be used in a
@@ -616,6 +620,8 @@ typedef List<PopupMenuEntry<T>> PopupMenuItemBuilder<T>(BuildContext context);
 /// the selected menu item. If child is null then a standard 'navigation/more_vert'
 /// icon is created.
 ///
+/// ## Sample code
+///
 /// This example shows a menu with four items, selecting between an enum's
 /// values and setting a `_selection` field based on the selection.
 ///

packages/flutter/lib/src/painting/box_fit.dart

@@ -3,7 +3,6 @@
 // found in the LICENSE file.
 
 import 'dart:math' as math;
-import 'dart:ui' show Image; // to disambiguate mentions of Image in the dartdocs
 
 import 'package:flutter/foundation.dart';
 
@@ -105,16 +104,18 @@ class FittedSizes {
 ///
 /// ## Sample code
 ///
-/// This example paints an [Image] `image` onto the [Rect] `outputRect` on a
-/// [Canvas] `canvas`, using a [Paint] paint, applying the [BoxFit] algorithm
+/// This function paints a [dart:ui.Image] `image` onto the [Rect] `outputRect` on a
+/// [Canvas] `canvas`, using a [Paint] `paint`, applying the [BoxFit] algorithm
 /// `fit`:
 ///
 /// ```dart
+/// void paintImage(ui.Image image, Rect outputRect, Canvas canvas, Paint paint, BoxFit fit) {
 ///   final Size imageSize = new Size(image.width.toDouble(), image.height.toDouble());
 ///   final FittedSizes sizes = applyBoxFit(fit, imageSize, outputRect.size);
 ///   final Rect inputSubrect = FractionalOffset.center.inscribe(sizes.source, Offset.zero & imageSize);
 ///   final Rect outputSubrect = FractionalOffset.center.inscribe(sizes.destination, outputRect);
 ///   canvas.drawImageRect(image, inputSubrect, outputSubrect, paint);
+/// }
 /// ```
 ///
 /// See also:

packages/flutter/lib/src/painting/box_painter.dart

@@ -328,18 +328,21 @@ class BorderSide {
 ///
 /// ## Sample code
 ///
+/// All four borders the same, two-pixel wide solid white:
+///
 /// ```dart
-/// // All four borders the same, two-pixel wide solid white:
 /// new Border.all(width: 2.0, color: const Color(0xFFFFFFFF))
 /// ```
 ///
+/// The border for a material design divider:
+///
 /// ```dart
-/// // The border for a material design divider:
 /// new Border(bottom: new BorderSide(color: Theme.of(context).dividerColor))
 /// ```
 ///
+/// A 1990s-era "OK" button:
+///
 /// ```dart
-/// // A 1990s-era "OK" button:
 /// new Container(
 ///   decoration: const BoxDecoration(
 ///     border: const Border(
@@ -1013,8 +1016,10 @@ class LinearGradient extends Gradient {
 ///
 /// ## Sample code
 ///
+/// This function draws a gradient that looks like a sun in a blue sky.
+///
 /// ```dart
-/// // This gradient looks like a sun in a blue sky.
+/// void paintSky(Canvas canvas, Rect rect) {
 ///   var gradient = new RadialGradient(
 ///     center: const FractionalOffset(0.7, 0.2), // near the top right
 ///     radius: 0.2,
@@ -1028,6 +1033,7 @@ class LinearGradient extends Gradient {
 ///   var paint = new Paint()
 ///     ..shader = gradient.createShader(rect);
 ///   canvas.drawRect(rect, paint);
+/// }
 /// ```
 ///
 /// See also:

packages/flutter/lib/src/painting/edge_insets.dart

@@ -26,14 +26,21 @@ enum Axis {
 ///
 /// Here are some examples of how to create [EdgeInsets] instances:
 ///
+/// Typical eight-pixel margin on all sides:
+///
 /// ```dart
-/// // typical 8-pixel margin on all sides
 /// const EdgeInsets.all(8.0)
+/// ```
+///
+/// Eight pixel margin above and below, no horizontal margins:
 ///
-/// // 8-pixel margin above and below, no horizontal margins
+/// ```dart
 /// const EdgeInsets.symmetric(vertical: 8.0)
+/// ```
 ///
-/// // left-margin indent of 40 pixels
+/// Left margin indent of 40 pixels:
+///
+/// ```dart
 /// const EdgeInsets.only(left: 40.0)
 /// ```
 ///
@@ -49,8 +56,9 @@ class EdgeInsets {
   ///
   /// ## Sample code
   ///
+  /// Typical eight-pixel margin on all sides:
+  ///
   /// ```dart
-  /// // typical 8-pixel margin on all sides
   /// const EdgeInsets.all(8.0)
   /// ```
   const EdgeInsets.all(double value)
@@ -60,8 +68,9 @@ class EdgeInsets {
   ///
   /// ## Sample code
   ///
+  /// Left margin indent of 40 pixels:
+  ///
   /// ```dart
-  /// // left-margin indent of 40 pixels
   /// const EdgeInsets.only(left: 40.0)
   /// ```
   const EdgeInsets.only({
@@ -75,8 +84,9 @@ class EdgeInsets {
   ///
   /// ## Sample code
   ///
+  /// Eight pixel margin above and below, no horizontal margins:
+  ///
   /// ```dart
-  /// // 8-pixel margin above and below, no horizontal margins
   /// const EdgeInsets.symmetric(vertical: 8.0)
   /// ```
   const EdgeInsets.symmetric({ double vertical: 0.0,

packages/flutter/lib/src/physics/gravity_simulation.dart

@@ -8,6 +8,30 @@ import 'simulation.dart';
 ///
 /// Models a particle that follows Newton's second law of motion. The simulation
 /// ends when the position reaches a defined point.
+///
+/// ## Sample code
+///
+/// This method triggers an [AnimationController] (a previously constructed
+/// `_controller` field) to simulate a fall of 300 pixels.
+///
+/// ```dart
+/// void _startFall() {
+///   _controller.animateWith(new GravitySimulation(
+///     10.0, // acceleration, pixels per second per second
+///     0.0, // starting position, pixels
+///     300.0, // ending position, pixels
+///     0.0, // starting velocity, pixels per second
+///   ));
+/// }
+/// ```
+///
+/// This [AnimationController] could be used with an [AnimatedBuilder] to
+/// animate the position of a child as if it was falling.
+///
+/// See also:
+///
+///  * [Curves.bounceOut], a [Curve] that has a similar aesthetics but includes
+///    a bouncing effect.
 class GravitySimulation extends Simulation {
   /// Creates a [GravitySimulation] using the given arguments, which are,
   /// respectively: an acceleration that is to be applied continually over time;

packages/flutter/lib/src/widgets/animated_cross_fade.dart

@@ -50,7 +50,7 @@ enum CrossFadeState {
 ///   duration: const Duration(seconds: 3),
 ///   firstChild: const FlutterLogo(style: FlutterLogoStyle.horizontal, size: 100.0),
 ///   secondChild: const FlutterLogo(style: FlutterLogoStyle.stacked, size: 100.0),
-///   crossFadeState: _on ? CrossFadeState.showFirst : CrossFadeState.showSecond,
+///   crossFadeState: _first ? CrossFadeState.showFirst : CrossFadeState.showSecond,
 /// )
 /// ```
 ///

packages/flutter/lib/src/widgets/async.dart

@@ -12,6 +12,9 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/widgets.dart';
 import 'package:meta/meta.dart' show required;
 
+// Examples can assume:
+// dynamic _lot;
+
 /// Base class for widgets that build themselves based on interaction with
 /// a specified [Stream].
 ///

packages/flutter/lib/src/widgets/basic.dart

@@ -350,7 +350,7 @@ class CustomPaint extends SingleChildRenderObjectWidget {
 ///   child: new Align(
 ///     alignment: FractionalOffset.topCenter,
 ///     heightFactor: 0.5,
-///     child: new Image(...),
+///     child: new Image.network(userAvatarUrl),
 ///   ),
 /// )
 /// ```

packages/flutter/lib/src/widgets/binding.dart

@@ -35,14 +35,14 @@ export 'dart:ui' show AppLifecycleState, Locale;
 /// lifecycle messages. See [didChangeAppLifecycleState].
 ///
 /// ```dart
-/// class Reactor extends StatefulWidget {
-///   const Reactor({ Key key }) : super(key: key);
+/// class AppLifecycleReactor extends StatefulWidget {
+///   const AppLifecycleReactor({ Key key }) : super(key: key);
 ///
 ///   @override
-///   _ReactorState createState() => new _ReactorState();
+///   _AppLifecycleReactorState createState() => new _AppLifecycleReactorState();
 /// }
 ///
-/// class _ReactorState extends State<Reactor> with WidgetsBindingObserver {
+/// class _AppLifecycleReactorState extends State<AppLifecycleReactor> with WidgetsBindingObserver {
 ///   @override
 ///   void initState() {
 ///     super.initState();
@@ -104,14 +104,14 @@ abstract class WidgetsBindingObserver {
   /// rotated (or otherwise changes dimensions).
   ///
   /// ```dart
-  /// class Reactor extends StatefulWidget {
-  ///   const Reactor({ Key key }) : super(key: key);
+  /// class MetricsReactor extends StatefulWidget {
+  ///   const MetricsReactor({ Key key }) : super(key: key);
   ///
   ///   @override
-  ///   _ReactorState createState() => new _ReactorState();
+  ///   _MetricsReactorState createState() => new _MetricsReactorState();
   /// }
   ///
-  /// class _ReactorState extends State<Reactor> with WidgetsBindingObserver {
+  /// class _MetricsReactorState extends State<MetricsReactor> with WidgetsBindingObserver {
   ///   @override
   ///   void initState() {
   ///     super.initState();

packages/flutter/lib/src/widgets/framework.dart

@@ -17,6 +17,15 @@ export 'package:flutter/foundation.dart' show FlutterError, debugPrint, debugPri
 export 'package:flutter/foundation.dart' show VoidCallback, ValueChanged, ValueGetter, ValueSetter;
 export 'package:flutter/rendering.dart' show RenderObject, RenderBox, debugDumpRenderTree, debugDumpLayerTree;
 
+// Examples can assume:
+// BuildContext context;
+// void setState(VoidCallback fn) { }
+
+// Examples can assume:
+// abstract class RenderFrogJar extends RenderObject { }
+// abstract class FrogJar extends RenderObjectWidget { }
+// abstract class FrogJarParentData extends ParentData { Size size; }
+
 // KEYS
 
 /// A [Key] is an identifier for [Widget]s and [Element]s.
@@ -643,20 +652,20 @@ abstract class StatelessWidget extends Widget {
 ///
 /// ## Sample code
 ///
-/// The following is a skeleton of a stateful widget subclass called `GreenFrog`:
+/// The following is a skeleton of a stateful widget subclass called `YellowBird`:
 ///
 /// ```dart
-/// class GreenFrog extends StatefulWidget {
-///   const GreenFrog({ Key key }) : super(key: key);
+/// class YellowBird extends StatefulWidget {
+///   const YellowBird({ Key key }) : super(key: key);
 ///
 ///   @override
-///   _GreenFrogState createState() => new _GreenFrogState();
+///   _YellowBirdState createState() => new _YellowBirdState();
 /// }
 ///
-/// class _GreenFrogState extends State<GreenFrog> {
+/// class _YellowBirdState extends State<YellowBird> {
 ///   @override
 ///   Widget build(BuildContext context) {
-///     return new Container(color: const Color(0xFF2DBD3A));
+///     return new Container(color: const Color(0xFFFFE306));
 ///   }
 /// }
 /// ```
@@ -665,15 +674,15 @@ abstract class StatelessWidget extends Widget {
 /// represented as private member fields. Also, normally widgets have more
 /// constructor arguments, each of which corresponds to a `final` property.
 ///
-/// The next example shows the more generic widget `Frog` which can be given a
+/// The next example shows the more generic widget `Bird` which can be given a
 /// color and a child, and which has some internal state with a method that
 /// can be called to mutate it:
 ///
 /// ```dart
-/// class Frog extends StatefulWidget {
-///   const Frog({
+/// class Bird extends StatefulWidget {
+///   const Bird({
 ///     Key key,
-///     this.color: const Color(0xFF2DBD3A),
+///     this.color: const Color(0xFFFFE306),
 ///     this.child,
 ///   }) : super(key: key);
 ///
@@ -681,10 +690,10 @@ abstract class StatelessWidget extends Widget {
 ///
 ///   final Widget child;
 ///
-///   _FrogState createState() => new _FrogState();
+///   _BirdState createState() => new _BirdState();
 /// }
 ///
-/// class _FrogState extends State<Frog> {
+/// class _BirdState extends State<Bird> {
 ///   double _size = 1.0;
 ///
 ///   void grow() {
@@ -695,7 +704,7 @@ abstract class StatelessWidget extends Widget {
 ///   Widget build(BuildContext context) {
 ///     return new Container(
 ///       color: widget.color,
-///       transform: new Matrix4.diagonalValues(_size, _size, 1.0),
+///       transform: new Matrix4.diagonal3Values(_size, _size, 1.0),
 ///       child: widget.child,
 ///     );
 ///   }
@@ -1309,7 +1318,7 @@ abstract class ProxyWidget extends Widget {
 ///
 /// ```dart
 /// class FrogSize extends ParentDataWidget<FrogJar> {
-///   Pond({
+///   FrogSize({
 ///     Key key,
 ///     @required this.size,
 ///     @required Widget child,
@@ -1425,7 +1434,7 @@ abstract class ParentDataWidget<T extends RenderObjectWidget> extends ProxyWidge
 ///
 /// ```dart
 /// class FrogColor extends InheritedWidget {
-///   const FrogColor(
+///   const FrogColor({
 ///     Key key,
 ///     @required this.color,
 ///     @required Widget child,

packages/flutter/lib/src/widgets/gesture_detector.dart

@@ -408,10 +408,10 @@ class GestureDetector extends StatelessWidget {
 ///       () => new TapGestureRecognizer(),
 ///       (TapGestureRecognizer instance) {
 ///         instance
-///           ..onTapDown = (TapDownDetails details) { setState(() { _last = 'down'; }); },
-///           ..onTapUp = (TapUpDetails details) { setState(() { _last = 'up'; }); },
-///           ..onTap = () { setState(() { _last = 'tap'; }); },
-///           ..onTapCancel = () { setState(() { _last = 'cancel'; }); },
+///           ..onTapDown = (TapDownDetails details) { setState(() { _last = 'down'; }); }
+///           ..onTapUp = (TapUpDetails details) { setState(() { _last = 'up'; }); }
+///           ..onTap = () { setState(() { _last = 'tap'; }); }
+///           ..onTapCancel = () { setState(() { _last = 'cancel'; }); };
 ///       },
 ///     ),
 ///   },