More documentation (#10589)

packages/flutter/lib/src/foundation/change_notifier.dart

@@ -20,7 +20,7 @@ abstract class Listenable {
   /// The list must not be changed after this method has been called. Doing so
   /// will lead to memory leaks or exceptions.
   ///
-  /// The list may contain `null`s; they are ignored.
+  /// The list may contain nulls; they are ignored.
   factory Listenable.merge(List<Listenable> listenables) = _MergingListenable;
 
   /// Register a closure to be called when the object notifies its listeners.

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

@@ -109,6 +109,11 @@ class TextPainter {
   /// passed to [layout].
   ///
   /// After this is set, you must call [layout] before the next call to [paint].
+  ///
+  /// The higher layers of the system, such as the [Text] widget, represent
+  /// overflow effects using the [TextOverflow] enum. The
+  /// [TextOverflow.ellipsis] value corresponds to setting this property to
+  /// U+2026 HORIZONTAL ELLIPSIS (…).
   String get ellipsis => _ellipsis;
   String _ellipsis;
   set ellipsis(String value) {

packages/flutter/lib/src/rendering/debug.dart

@@ -108,7 +108,11 @@ bool debugPrintMarkNeedsLayoutStacks = false;
 /// Check the intrinsic sizes of each [RenderBox] during layout.
 bool debugCheckIntrinsicSizes = false;
 
-/// Adds [dart:developer.Timeline] events for every RenderObject painted.
+/// Adds [dart:developer.Timeline] events for every [RenderObject] painted.
+///
+/// This is only enabled in debug builds. The timing information this exposes is
+/// not representative of actual paints. However, it can expose unexpected
+/// painting in the timeline.
 ///
 /// For details on how to use [dart:developer.Timeline] events in the Dart
 /// Observatory to optimize your app, see:

packages/flutter/lib/src/rendering/object.dart

@@ -2401,7 +2401,7 @@ abstract class RenderObject extends AbstractNode implements HitTestTarget {
   /// the approximate bounding box of the clip rect that would be
   /// applied to the given child during the paint phase, if any.
   ///
-  /// Returns `null` if the child would not be clipped.
+  /// Returns null if the child would not be clipped.
   ///
   /// This is used in the semantics phase to avoid including children
   /// that are not physically visible.

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

@@ -119,7 +119,7 @@ class PageStorage extends StatelessWidget {
 
   /// The bucket from the closest instance of this class that encloses the given context.
   ///
-  /// Returns `null` if none exists.
+  /// Returns null if none exists.
   ///
   /// Typical usage is as follows:
   ///

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

@@ -524,7 +524,7 @@ abstract class ModalRoute<T> extends TransitionRoute<T> with LocalHistoryRoute<T
 
   /// Returns the modal route most closely associated with the given context.
   ///
-  /// Returns `null` if the given context is not associated with a modal route.
+  /// Returns null if the given context is not associated with a modal route.
   ///
   /// Typical usage is as follows:
   ///

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

@@ -15,7 +15,7 @@ export 'package:flutter/rendering.dart' show RelativeRect;
 
 /// A widget that rebuilds when the given [Listenable] changes value.
 ///
-/// [AnimatedWidget] is most common used with [Animation] objects, which are
+/// [AnimatedWidget] is most commonly used with [Animation] objects, which are
 /// [Listenable], but it can be used with any [Listenable], including
 /// [ChangeNotifier] and [ValueNotifier].
 ///
@@ -450,6 +450,11 @@ typedef Widget TransitionBuilder(BuildContext context, Widget child);
 /// an animation as part of a larger build function. To use AnimatedBuilder,
 /// simply construct the widget and pass it a builder function.
 ///
+/// For simple cases without additional state, consider using
+/// [AnimatedWidget].
+///
+/// ## Performance optimisations
+///
 /// If your [builder] function contains a subtree that does not depend on the
 /// animation, it's more efficient to build that subtree once instead of
 /// rebuilding it on every animation tick.
@@ -461,8 +466,51 @@ typedef Widget TransitionBuilder(BuildContext context, Widget child);
 /// Using this pre-built child is entirely optional, but can improve
 /// performance significantly in some cases and is therefore a good practice.
 ///
-/// For simple cases without additional state, consider using
-/// [AnimatedWidget].
+/// ## Sample code
+///
+/// This code defines a widget called `Spinner` that spins a green square
+/// continually. It is built with an [AnimatedBuilder] and makes use of the
+/// [child] feature to avoid having to rebuild the [Container] each time.
+///
+/// ```dart
+/// class Spinner extends StatefulWidget {
+///   @override
+///   _SpinnerState createState() => new _SpinnerState();
+/// }
+///
+/// class _SpinnerState extends State<Spinner> with SingleTickerProviderStateMixin {
+///   AnimationController _controller;
+///
+///   @override
+///   void initState() {
+///     super.initState();
+///     _controller = new AnimationController(
+///       duration: const Duration(seconds: 10),
+///       vsync: this,
+///     )..repeat();
+///   }
+///
+///   @override
+///   void dispose() {
+///     _controller.dispose();
+///     super.dispose();
+///   }
+///
+///   @override
+///   Widget build(BuildContext context) {
+///     return new AnimatedBuilder(
+///       animation: _controller,
+///       child: new Container(width: 200.0, height: 200.0, color: Colors.green),
+///       builder: (BuildContext context, Widget child) {
+///         return new Transform.rotate(
+///           angle: _controller.value * 2.0 * math.PI,
+///           child: child,
+///         );
+///       },
+///     );
+///   }
+/// }
+/// ```
 class AnimatedBuilder extends AnimatedWidget {
   /// Creates an animated builder.
   ///

packages/flutter_driver/lib/src/driver.dart

@@ -158,8 +158,8 @@ class FlutterDriver {
     VMIsolate isolate = await vm.isolates.first.loadRunnable();
 
     // TODO(yjbanov): vm_service_client does not support "None" pause event yet.
-    // It is currently reported as `null`, but we cannot rely on it because
-    // eventually the event will be reported as a non-`null` object. For now,
+    // It is currently reported as null, but we cannot rely on it because
+    // eventually the event will be reported as a non-null object. For now,
     // list all the events we know about. Later we'll check for "None" event
     // explicitly.
     //

packages/flutter_driver/lib/src/extension.dart

@@ -49,13 +49,14 @@ void enableFlutterDriverExtension() {
   assert(WidgetsBinding.instance is _DriverBinding);
 }
 
-/// Handles a command and returns a result.
+/// Signature for functions that handle a command and return a result.
 typedef Future<Result> CommandHandlerCallback(Command c);
 
-/// Deserializes JSON map to a command object.
+/// Signature for functions that deserialize a JSON map to a command object.
 typedef Command CommandDeserializerCallback(Map<String, String> params);
 
-/// Runs the finder and returns the [Element] found, or `null`.
+/// Signature for functions that run the given finder and return the [Element]
+/// found, if any, or null otherwise.
 typedef Finder FinderConstructor(SerializableFinder finder);
 
 @visibleForTesting

packages/flutter_driver/lib/src/timeline_summary.dart

@@ -28,14 +28,14 @@ class TimelineSummary {
   /// Average amount of time spent per frame in the framework building widgets,
   /// updating layout, painting and compositing.
   ///
-  /// Returns `null` if no frames were recorded.
+  /// Returns null if no frames were recorded.
   double computeAverageFrameBuildTimeMillis() {
     return _averageInMillis(_extractFrameThreadDurations());
   }
 
   /// The longest frame build time in milliseconds.
   ///
-  /// Returns `null` if no frames were recorded.
+  /// Returns null if no frames were recorded.
   double computeWorstFrameBuildTimeMillis() {
     return _maxInMillis(_extractFrameThreadDurations());
   }
@@ -48,14 +48,14 @@ class TimelineSummary {
 
   /// Average amount of time spent per frame in the GPU rasterizer.
   ///
-  /// Returns `null` if no frames were recorded.
+  /// Returns null if no frames were recorded.
   double computeAverageFrameRasterizerTimeMillis() {
     return _averageInMillis(_extractDuration(_extractGpuRasterizerDrawEvents()));
   }
 
   /// The longest frame rasterization time in milliseconds.
   ///
-  /// Returns `null` if no frames were recorded.
+  /// Returns null if no frames were recorded.
   double computeWorstFrameRasterizerTimeMillis() {
     return _maxInMillis(_extractDuration(_extractGpuRasterizerDrawEvents()));
   }

packages/flutter_tools/lib/src/android/android_device.dart

@@ -476,7 +476,7 @@ class AndroidDevice extends Device {
 
   static final RegExp _timeRegExp = new RegExp(r'^\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}', multiLine: true);
 
-  /// Return the most recent timestamp in the Android log or `null` if there is
+  /// Return the most recent timestamp in the Android log or null if there is
   /// no available timestamp. The format can be passed to logcat's -T option.
   String get lastLogcatTimestamp {
     final String output = runCheckedSync(adbCommandForDevice(<String>[

packages/flutter_tools/lib/src/asset.dart

@@ -316,7 +316,7 @@ DevFSContent _createFontManifest(Map<String, dynamic> manifestDescriptor,
 /// Given an assetBase location and a pubspec.yaml Flutter manifest, return a
 /// map of assets to asset variants.
 ///
-/// Returns `null` on missing assets.
+/// Returns null on missing assets.
 Map<_Asset, List<_Asset>> _parseAssets(
   PackageMap packageMap,
   Map<String, dynamic> manifestDescriptor,

packages/flutter_tools/lib/src/base/os.dart

@@ -27,7 +27,7 @@ abstract class OperatingSystemUtils {
   /// Make the given file executable. This may be a no-op on some platforms.
   ProcessResult makeExecutable(File file);
 
-  /// Return the path (with symlinks resolved) to the given executable, or `null`
+  /// Return the path (with symlinks resolved) to the given executable, or null
   /// if `which` was not able to locate the binary.
   File which(String execName) {
     final List<File> result = _which(execName);
@@ -206,7 +206,7 @@ class _WindowsUtils extends OperatingSystemUtils {
 
 /// Find and return the project root directory relative to the specified
 /// directory or the current working directory if none specified.
-/// Return `null` if the project root could not be found
+/// Return null if the project root could not be found
 /// or if the project root is the flutter repository root.
 String findProjectRoot([String directory]) {
   const String kProjectRootSentinel = 'pubspec.yaml';

packages/flutter_tools/lib/src/commands/build_aot.dart

@@ -82,7 +82,7 @@ String _getPackagePath(PackageMap packageMap, String package) {
   return fs.path.dirname(packageMap.map[package].toFilePath());
 }
 
-/// Build an AOT snapshot. Return `null` (and log to `printError`) if the method
+/// Build an AOT snapshot. Return null (and log to `printError`) if the method
 /// fails.
 Future<String> buildAotSnapshot(
   String mainPath,

packages/flutter_tools/lib/src/commands/config.dart

@@ -42,7 +42,7 @@ class ConfigCommand extends FlutterCommand {
       'Analytics reporting is currently ${flutterUsage.enabled ? 'enabled' : 'disabled'}.';
   }
 
-  /// Return `null` to disable tracking of the `config` command.
+  /// Return null to disable tracking of the `config` command.
   @override
   Future<String> get usagePath => null;
 

packages/flutter_tools/lib/src/commands/create.dart

@@ -311,7 +311,7 @@ final Set<String> _packageDependencies = new Set<String>.from(<String>[
   'yaml'
 ]);
 
-/// Return `null` if the project name is legal. Return a validation message if
+/// Return null if the project name is legal. Return a validation message if
 /// we should disallow the project name.
 String _validateProjectName(String projectName) {
   if (!package_names.isValidPackageName(projectName))
@@ -324,7 +324,7 @@ String _validateProjectName(String projectName) {
   return null;
 }
 
-/// Return `null` if the project directory is legal. Return a validation message
+/// Return null if the project directory is legal. Return a validation message
 /// if we should disallow the directory name.
 String _validateProjectDir(String dirPath, { String flutterRoot }) {
   if (fs.path.isWithin(flutterRoot, dirPath)) {

packages/flutter_tools/lib/src/dart/analysis.dart

@@ -136,7 +136,7 @@ class AnalysisDriver {
 
   bool _isFiltered(AnalysisError error) {
     final ErrorProcessor processor = ErrorProcessor.getProcessor(context.analysisOptions, error);
-    // Filtered errors are processed to a severity of `null`.
+    // Filtered errors are processed to a severity of null.
     return processor != null && processor.severity == null;
   }
 

packages/flutter_tools/lib/src/runner/flutter_command.dart

@@ -134,7 +134,7 @@ abstract class FlutterCommand extends Command<Null> {
     applicationPackages ??= new ApplicationPackageStore();
   }
 
-  /// The path to send to Google Analytics. Return `null` here to disable
+  /// The path to send to Google Analytics. Return null here to disable
   /// tracking of the command.
   Future<String> get usagePath async => name;
 
@@ -218,7 +218,7 @@ abstract class FlutterCommand extends Command<Null> {
   /// Find and return all target [Device]s based upon currently connected
   /// devices and criteria entered by the user on the command line.
   /// If no device can be found that meets specified criteria,
-  /// then print an error message and return `null`.
+  /// then print an error message and return null.
   Future<List<Device>> findAllTargetDevices() async {
     if (!doctor.canLaunchAnything) {
       printError("Unable to locate a development device; please run 'flutter doctor' "
@@ -264,7 +264,7 @@ abstract class FlutterCommand extends Command<Null> {
   /// Find and return the target [Device] based upon currently connected
   /// devices and criteria entered by the user on the command line.
   /// If a device cannot be found that meets specified criteria,
-  /// then print an error message and return `null`.
+  /// then print an error message and return null.
   Future<Device> findTargetDevice() async {
     List<Device> deviceList = await findAllTargetDevices();
     if (deviceList == null)

packages/flutter_tools/lib/src/version.dart

@@ -236,7 +236,7 @@ class FlutterVersion {
   /// This method sends a server request if it's been more than
   /// [kCheckAgeConsideredUpToDate] since the last version check.
   ///
-  /// Returns `null` if the cached version is out-of-date or missing, and we are
+  /// Returns null if the cached version is out-of-date or missing, and we are
   /// unable to reach the server to get the latest version.
   Future<DateTime> _getLatestAvailableFlutterVersion() async {
     Cache.checkLockAcquired();