More docs updates for services. (#7633)

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

@@ -14,7 +14,7 @@ import 'platform_messages.dart';
 /// Listens for platform messages and directs them to [PlatformMessages].
 ///
 /// The ServicesBinding also registers a [LicenseEntryCollector] that exposes
-/// the licenses found in the LICENSE file stored at the root of the asset
+/// the licenses found in the `LICENSE` file stored at the root of the asset
 /// bundle.
 abstract class ServicesBinding extends BindingBase {
   @override

packages/flutter/lib/src/services/clipboard.dart

@@ -6,27 +6,31 @@ import 'dart:async';
 
 import 'platform_messages.dart';
 
-/// Data stored on the system clip board.
+/// Data stored on the system clipboard.
 ///
-/// The system clip board can contain data of various media types. This data
-/// structure currently supports only plain text data in the [text] property.
+/// The system clipboard can contain data of various media types. This data
+/// structure currently supports only plain text data, in the [text] property.
 class ClipboardData {
   /// Creates data for the system clipboard.
   const ClipboardData({ this.text });
 
-  /// Plain text data on the clip board.
+  /// Plain text variant of this clipboard data.
   final String text;
 }
 
 const String _kChannelName = 'flutter/platform';
 
-/// An interface to the system's clipboard.
+/// Utility methods for interacting with the system's clipboard.
 class Clipboard {
-  /// Constants for common [getData] [format] types.
-  static final String kTextPlain = 'text/plain';
-
   Clipboard._();
 
+  // Constants for common [getData] [format] types.
+
+  /// Plain text data format string.
+  ///
+  /// Used with [getData].
+  static const String kTextPlain = 'text/plain';
+
   /// Stores the given clipboard data on the clipboard.
   static Future<Null> setData(ClipboardData data) async {
     await PlatformMessages.invokeMethod(
@@ -40,10 +44,17 @@ class Clipboard {
 
   /// Retrieves data from the clipboard that matches the given format.
   ///
-  ///  * `format` is a media type, such as `text/plain`.
+  /// The `format` argument specifies the media type, such as `text/plain`, of
+  /// the data to obtain.
+  ///
+  /// Returns a future which completes to null if the data could not be
+  /// obtained, and to a [ClipboardData] object if it could.
   static Future<ClipboardData> getData(String format) async {
     Map<String, dynamic> result = await PlatformMessages.invokeMethod(
-        _kChannelName, 'Clipboard.getData', <String>[format]);
+      _kChannelName,
+      'Clipboard.getData',
+      <String>[format]
+    );
     if (result == null)
       return null;
     return new ClipboardData(text: result['text']);

packages/flutter/lib/src/services/haptic_feedback.dart

@@ -6,21 +6,20 @@ import 'dart:async';
 
 import 'platform_messages.dart';
 
-/// Allows access to the haptic feedback interface on the device. This API is
-/// intentionally terse since it calls default platform behavior. It is not
-/// suitable for use if you require more flexible access to device sensors and
-/// peripherals.
+/// Allows access to the haptic feedback interface on the device.
+///
+/// This API is intentionally terse since it calls default platform behavior. It
+/// is not suitable for precise control of the system's haptic feedback module.
 class HapticFeedback {
   HapticFeedback._();
 
   /// Provides haptic feedback to the user for a short duration.
   ///
-  /// Platform Specific Notes:
+  /// On iOS, this uses the platform "sound" for vibration (via
+  /// `AudioServicesPlaySystemSound`).
   ///
-  /// * _iOS_: Uses the platform "sound" for vibration (via
-  ///   AudioServicesPlaySystemSound)
-  /// * _Android_: Uses the platform haptic feedback API that simulates a short
-  ///   a short tap on a virtual keyboard.
+  /// On Android, this uses the platform haptic feedback API to simulates a
+  /// short tap on a virtual keyboard.
   static Future<Null> vibrate() async {
     await PlatformMessages.invokeMethod('flutter/platform', 'HapticFeedback.vibrate');
   }

packages/flutter/lib/src/services/path_provider.dart

@@ -13,16 +13,16 @@ const String _kChannelName = 'flutter/platform';
 class PathProvider {
   PathProvider._();
 
-  /// Path to the temporary directory on the device. Files in this directory
-  /// may be cleared at any time. This does *not* return a new temporary
-  /// directory. Instead, the caller is responsible for creating
+  /// Path to the temporary directory on the device.
+  ///
+  /// Files in this directory may be cleared at any time. This does *not* return
+  /// a new temporary directory. Instead, the caller is responsible for creating
   /// (and cleaning up) files or directories within this directory. This
   /// directory is scoped to the calling application.
   ///
-  /// Examples:
+  /// On iOS, this uses the `NSTemporaryDirectory` API.
   ///
-  ///  * _iOS_: `NSTemporaryDirectory()`
-  ///  * _Android_: `getCacheDir()` on the context.
+  /// On Android, this uses the `getCacheDir` API on the context.
   static Future<Directory> getTemporaryDirectory() async {
     Map<String, dynamic> result = await PlatformMessages.invokeMethod(
         _kChannelName, 'PathProvider.getTemporaryDirectory');
@@ -35,10 +35,9 @@ class PathProvider {
   /// to the application and will only be cleared when the application itself
   /// is deleted.
   ///
-  /// Examples:
+  /// On iOS, this uses the `NSDocumentsDirectory` API.
   ///
-  ///  * _iOS_: `NSDocumentsDirectory`
-  ///  * _Android_: The AppData directory.
+  /// On Android, this returns the AppData directory.
   static Future<Directory> getApplicationDocumentsDirectory() async {
     Map<String, dynamic> result = await PlatformMessages.invokeMethod(
         _kChannelName, 'PathProvider.getApplicationDocumentsDirectory');

packages/flutter/lib/src/services/platform_messages.dart

@@ -30,15 +30,17 @@ dynamic _decodeJSON(String message) {
 
 typedef Future<ByteData> _PlatformMessageHandler(ByteData message);
 
-/// Sends message to and receives messages from the underlying platform.
+/// Sends message to and receives messages from platform plugins.
+///
+/// See: <https://flutter.io/platform-services/>
 class PlatformMessages {
   PlatformMessages._();
 
-  /// Handlers for incoming platform messages.
+  // Handlers for incoming messages from platform plugins.
   static final Map<String, _PlatformMessageHandler> _handlers =
       <String, _PlatformMessageHandler>{};
 
-  /// Mock handlers that intercept and respond to outgoing messages.
+  // Mock handlers that intercept and respond to outgoing messages.
   static final Map<String, _PlatformMessageHandler> _mockHandlers =
       <String, _PlatformMessageHandler>{};
 
@@ -85,7 +87,10 @@ class PlatformMessages {
     }
   }
 
-  /// Send a binary message to the host application.
+  /// Send a binary message to the platform plugins on the given channel.
+  ///
+  /// Returns a [Future] which completes to the received response, undecoded, in
+  /// binary form.
   static Future<ByteData> sendBinary(String channel, ByteData message) {
     final _PlatformMessageHandler handler = _mockHandlers[channel];
     if (handler != null)
@@ -93,16 +98,37 @@ class PlatformMessages {
     return _sendPlatformMessage(channel, message);
   }
 
-  /// Send a string message to the host application.
+  /// Send a string message to the platform plugins on the given channel.
+  ///
+  /// The message is encoded as UTF-8.
+  ///
+  /// Returns a [Future] which completes to the received response, decoded as a
+  /// UTF-8 string, or to an error, if the decoding fails.
   static Future<String> sendString(String channel, String message) async {
     return _decodeUTF8(await sendBinary(channel, _encodeUTF8(message)));
   }
 
-  /// Sends a JSON-encoded message to the host application and JSON-decodes the response.
+  /// Send a JSON-encoded message to the platform plugins on the given channel.
+  ///
+  /// The message is encoded as JSON, then the JSON is encoded as UTF-8.
+  ///
+  /// Returns a [Future] which completes to the received response, decoded as a
+  /// UTF-8-encoded JSON representation of a JSON value (a [String], [bool],
+  /// [double], [List], or [Map]), or to an error, if the decoding fails.
   static Future<dynamic> sendJSON(String channel, dynamic json) async {
     return _decodeJSON(await sendString(channel, _encodeJSON(json)));
   }
 
+  /// Send a method call to the platform plugins on the given channel.
+  ///
+  /// Method calls are encoded as a JSON object with two keys, `method` with the
+  /// string given in the `method` argument, and `args` with the arguments given
+  /// in the `args` optional argument, as a JSON list. This JSON object is then
+  /// encoded as a UTF-8 string.
+  ///
+  /// The response from the method call is decoded as UTF-8, then the UTF-8 is
+  /// decoded as JSON. The returned [Future] completes to this fully decoded
+  /// response, or to an error, if the decoding fails.
   static Future<dynamic> invokeMethod(String channel, String method, [ List<dynamic> args = const <Null>[] ]) {
     return sendJSON(channel, <String, dynamic>{
       'method': method,
@@ -110,39 +136,56 @@ class PlatformMessages {
     });
   }
 
-  /// Set a callback for receiving binary messages from the platform.
+  /// Set a callback for receiving messages from the platform plugins on the
+  /// given channel, without decoding them.
+  ///
+  /// The given callback will replace the currently registered callback for that
+  /// channel, if any.
   ///
-  /// The given callback will replace the currently registered callback (if any).
+  /// The handler's return value, if non-null, is sent as a response, unencoded.
   static void setBinaryMessageHandler(String channel, Future<ByteData> handler(ByteData message)) {
     _handlers[channel] = handler;
   }
 
-  /// Set a callback for receiving string messages from the platform.
+  /// Set a callback for receiving messages from the platform plugins on the
+  /// given channel, decoding the data as UTF-8.
   ///
-  /// The given callback will replace the currently registered callback (if any).
+  /// The given callback will replace the currently registered callback for that
+  /// channel, if any.
+  ///
+  /// The handler's return value, if non-null, is sent as a response, encoded as
+  /// a UTF-8 string.
   static void setStringMessageHandler(String channel, Future<String> handler(String message)) {
     setBinaryMessageHandler(channel, (ByteData message) async {
       return _encodeUTF8(await handler(_decodeUTF8(message)));
     });
   }
 
-  /// Set a callback for receiving JSON messages from the platform.
+  /// Set a callback for receiving messages from the platform plugins on the
+  /// given channel, decoding the data as UTF-8 JSON.
   ///
-  /// Messages received are decoded as JSON before being passed to the given
-  /// callback. The result of the callback is encoded as JSON before being
-  /// returned as the response to the message.
+  /// The given callback will replace the currently registered callback for that
+  /// channel, if any.
   ///
-  /// The given callback will replace the currently registered callback (if any).
+  /// The handler's return value, if non-null, is sent as a response, encoded as
+  /// JSON and then as a UTF-8 string.
   static void setJSONMessageHandler(String channel, Future<dynamic> handler(dynamic message)) {
     setStringMessageHandler(channel, (String message) async {
       return _encodeJSON(await handler(_decodeJSON(message)));
     });
   }
 
-  /// Sets a message handler that intercepts outgoing messages in binary form.
+  /// Set a mock callback for intercepting messages from the `send*` methods on
+  /// this class, on the given channel, without decoding them.
+  ///
+  /// The given callback will replace the currently registered mock callback for
+  /// that channel, if any. To remove the mock handler, pass `null` as the
+  /// `handler` argument.
   ///
-  /// The given callback will replace the currently registered callback (if any).
-  /// To remove the mock handler, pass `null` as the `handler` argument.
+  /// The handler's return value, if non-null, is used as a response, unencoded.
+  ///
+  /// This is intended for testing. Messages intercepted in this manner are not
+  /// sent to platform plugins.
   static void setMockBinaryMessageHandler(String channel, Future<ByteData> handler(ByteData message)) {
     if (handler == null)
       _mockHandlers.remove(channel);
@@ -150,10 +193,18 @@ class PlatformMessages {
       _mockHandlers[channel] = handler;
   }
 
-  /// Sets a message handler that intercepts outgoing messages in string form.
+  /// Set a mock callback for intercepting messages from the `send*` methods on
+  /// this class, on the given channel, decoding them as UTF-8.
+  ///
+  /// The given callback will replace the currently registered mock callback for
+  /// that channel, if any. To remove the mock handler, pass `null` as the
+  /// `handler` argument.
   ///
-  /// The given callback will replace the currently registered callback (if any).
-  /// To remove the mock handler, pass `null` as the `handler` argument.
+  /// The handler's return value, if non-null, is used as a response, encoded as
+  /// UTF-8.
+  ///
+  /// This is intended for testing. Messages intercepted in this manner are not
+  /// sent to platform plugins.
   static void setMockStringMessageHandler(String channel, Future<String> handler(String message)) {
     if (handler == null) {
       setMockBinaryMessageHandler(channel, null);
@@ -164,10 +215,18 @@ class PlatformMessages {
     }
   }
 
-  /// Sets a message handler that intercepts outgoing messages in JSON form.
+  /// Set a mock callback for intercepting messages from the `send*` methods on
+  /// this class, on the given channel, decoding them as UTF-8 JSON.
+  ///
+  /// The given callback will replace the currently registered mock callback for
+  /// that channel, if any. To remove the mock handler, pass `null` as the
+  /// `handler` argument.
+  ///
+  /// The handler's return value, if non-null, is used as a response, encoded as
+  /// UTF-8 JSON.
   ///
-  /// The given callback will replace the currently registered callback (if any).
-  /// To remove the mock handler, pass `null` as the `handler` argument.
+  /// This is intended for testing. Messages intercepted in this manner are not
+  /// sent to platform plugins.
   static void setMockJSONMessageHandler(String channel, Future<dynamic> handler(dynamic message)) {
     if (handler == null) {
       setMockStringMessageHandler(channel, null);

packages/flutter/lib/src/services/raw_keyboard.dart

@@ -16,6 +16,7 @@ import 'platform_messages.dart';
 /// See also:
 ///
 ///  * [RawKeyEventDataAndroid]
+ //  * [RawKeyEventDataFuchsia]
 ///  * [RawKeyEvent]
 ///  * [RawKeyDownEvent]
 ///  * [RawKeyUpEvent]
@@ -28,7 +29,7 @@ abstract class RawKeyEventData {
 /// Platform-specific key event data for Android.
 ///
 /// This object contains information about key events obtained from Android's
-/// KeyEvent interface.
+/// `KeyEvent` interface.
 class RawKeyEventDataAndroid extends RawKeyEventData {
   /// Creates a key event data structure specific for Android.
   ///
@@ -61,7 +62,7 @@ class RawKeyEventDataAndroid extends RawKeyEventData {
 /// Platform-specific key event data for Fuchsia.
 ///
 /// This object contains information about key events obtained from Fuchsia's
-/// KeyData interface.
+/// `KeyData` interface.
 class RawKeyEventDataFuchsia extends RawKeyEventData {
   /// Creates a key event data structure specific for Android.
   ///
@@ -77,9 +78,9 @@ class RawKeyEventDataFuchsia extends RawKeyEventData {
   /// See <http://www.usb.org/developers/hidpage/Hut1_12v2.pdf>
   final int hidUsage;
 
-  /// The unicode code point represented by the key event, if any.
+  /// The Unicode code point represented by the key event, if any.
   ///
-  /// If there is no unicode code point, this value is zero.
+  /// If there is no Unicode code point, this value is zero.
   final int codePoint;
 
   /// The modifiers that we present when the key event occured.

packages/flutter/lib/src/services/system_navigator.dart

@@ -13,10 +13,12 @@ class SystemNavigator {
   /// Instructs the system navigator to remove this activity from the stack and
   /// return to the previous activity.
   ///
-  /// Platform Specific Notes:
+  /// On iOS, calls to this method are ignored because Apple's human interface
+  /// guidelines state that applications should not exit themselves.
   ///
-  ///   On iOS, this is a no-op because Apple's human interface guidelines state
-  ///   that applications should not exit themselves.
+  /// This method should be preferred over calling `dart:io`'s [exit] method, as
+  /// the latter may cause the underlying platform to act as if the application
+  /// had crashed.
   static Future<Null> pop() async {
     await PlatformMessages.invokeMethod('flutter/platform', 'SystemNavigator.pop');
   }

packages/flutter/lib/src/services/system_sound.dart

@@ -6,19 +6,19 @@ import 'dart:async';
 
 import 'platform_messages.dart';
 
-/// A sound provided by the system
+/// A sound provided by the system.
 enum SystemSoundType {
   /// A short indication that a button was pressed.
   click,
 }
 
-/// Allows easy access to the library of short system specific sounds for
-/// common tasks.
+/// Provides access to the library of short system specific sounds for common
+/// tasks.
 class SystemSound {
   SystemSound._();
 
   /// Play the specified system sound. If that sound is not present on the
-  /// system, this method is a no-op.
+  /// system, the call is ignored.
   static Future<Null> play(SystemSoundType type) async {
     await PlatformMessages.invokeMethod(
       'flutter/platform',

packages/flutter/lib/src/services/url_launcher.dart

@@ -13,11 +13,6 @@ class UrlLauncher {
 
   /// Parse the specified URL string and delegate handling of the same to the
   /// underlying platform.
-  ///
-  /// Arguments:
-  ///
-  /// * [urlString]: The URL string to be parsed by the underlying platform and
-  ///   before it attempts to launch the same.
   static Future<Null> launch(String urlString) async {
     await PlatformMessages.invokeMethod(
       'flutter/platform',