Reword the SystemChrome docs to be in the Flutter voice and style. (#7599)

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

@@ -8,19 +8,20 @@ import 'platform_messages.dart';
 
 /// Specifies a particular device orientation.
 ///
-/// Discussion:
-///
 /// To determine which values correspond to which orientations, first position
 /// the device in its default orientation (this is the orientation that the
 /// system first uses for its boot logo, or the orientation in which the
 /// hardware logos or markings are upright, or the orientation in which the
 /// cameras are at the top). If this is a portrait orientation, then this is
-/// [portraitUp]. Otherwise, it's [landscapeLeft]. As you rotate the device by 90
-/// degrees in a counter-clockwise direction around the axis that traverses the
-/// screen, you step through each value in this enum in the order given. (For a
-/// device with a landscape default orientation, the orientation obtained by
-/// rotating the device 90 degrees clockwise from its default orientation is
-/// [portraitUp].)
+/// [portraitUp]. Otherwise, it's [landscapeLeft]. As you rotate the device by
+/// 90 degrees in a counter-clockwise direction around the axis that pierces the
+/// screen, you step through each value in this enum in the order given.
+///
+/// For a device with a landscape default orientation, the orientation obtained
+/// by rotating the device 90 degrees clockwise from its default orientation is
+/// [portraitUp].
+///
+/// Used by [SystemChrome.setPreferredOrientations].
 enum DeviceOrientation {
   /// If the device shows its boot logo in portrait, then the boot logo is shown
   /// in [portraitUp]. Otherwise, the device shows its boot logo in landscape
@@ -29,6 +30,9 @@ enum DeviceOrientation {
   portraitUp,
 
   /// The orientation that is 90 degrees clockwise from [portraitUp].
+  ///
+  /// If the device shows its boot logo in landscape, then the boot logo is
+  /// shown in [landscapeLeft].
   landscapeLeft,
 
   /// The orientation that is 180 degrees from [portraitUp].
@@ -39,7 +43,10 @@ enum DeviceOrientation {
 }
 
 /// Specifies a description of the application that is pertinent to the
-/// embedder's application switcher (a.k.a. "recent tasks") user interface.
+/// embedder's application switcher (also known as "recent tasks") user
+/// interface.
+///
+/// Used by [SystemChrome.setApplicationSwitcherDescription].
 class ApplicationSwitcherDescription {
   /// Creates an ApplicationSwitcherDescription.
   const ApplicationSwitcherDescription({ this.label, this.primaryColor });
@@ -48,23 +55,28 @@ class ApplicationSwitcherDescription {
   final String label;
 
   /// The application's primary color.
+  ///
+  /// This may influence the color that the operating system uses to represent
+  /// the application.
   final int primaryColor;
 }
 
-/// Specifies a system overlay at a particular location. Certain platforms
-/// may not use all overlays specified here.
+/// Specifies a system overlay at a particular location.
+///
+/// Used by [SystemChrome.setEnabledSystemUIOverlays].
 enum SystemUiOverlay {
   /// The status bar provided by the embedder on the top of the application
-  /// surface (optional)
+  /// surface, if any.
   top,
 
   /// The status bar provided by the embedder on the bottom of the application
-  /// surface (optional)
+  /// surface, if any.
   bottom,
 }
 
-/// Specifies a preference for the style of the system overlays. Certain
-/// platforms may not respect this preference.
+/// Specifies a preference for the style of the system overlays.
+///
+/// Used by [SystemChrome.setSystemUIOverlayStyle].
 enum SystemUiOverlayStyle {
   /// System overlays should be drawn with a light color. Intended for
   /// applications with a dark background.
@@ -84,17 +96,16 @@ List<String> _stringify(List<dynamic> list) {
   return result;
 }
 
-/// Controls specific aspects of the embedder interface.
+/// Controls specific aspects of the operating system's graphical interface and
+/// how it interacts with the application.
 class SystemChrome {
   SystemChrome._();
 
   /// Specifies the set of orientations the application interface can
   /// be displayed in.
   ///
-  /// Arguments:
-  ///
-  ///  * [orientation]: A list of [DeviceOrientation] enum values. The empty
-  ///    list is synonymous with having all options enabled.
+  /// The `orientation` argument is a list of [DeviceOrientation] enum values.
+  /// The empty list is synonymous with having all options enabled.
   static Future<Null> setPreferredOrientations(List<DeviceOrientation> orientations) async {
     await PlatformMessages.invokeMethod(
       _kChannelName,
@@ -104,16 +115,10 @@ class SystemChrome {
   }
 
   /// Specifies the description of the current state of the application as it
-  /// pertains to the application switcher (a.k.a "recent tasks").
-  ///
-  /// Arguments:
-  ///
-  ///  * [description]: The application description.
-  ///
-  /// Platform Specific Notes:
+  /// pertains to the application switcher (also known as "recent tasks").
   ///
-  ///   If application-specified metadata is unsupported on the platform,
-  ///   specifying it is a no-op and always return true.
+  /// Any part of the description that is unsupported on the current platform
+  /// will be ignored.
   static Future<Null> setApplicationSwitcherDescription(ApplicationSwitcherDescription description) async {
     await PlatformMessages.invokeMethod(
       _kChannelName,
@@ -125,19 +130,14 @@ class SystemChrome {
     );
   }
 
-  /// Specifies the set of overlays visible on the embedder when the
-  /// application is running. The embedder may choose to ignore unsupported
-  /// overlays
+  /// Specifies the set of system overlays to have visible when the application
+  /// is running.
   ///
-  /// Arguments:
+  /// The `overlays` argument is a list of [SystemUiOverlay] enum values
+  /// denoting the overlays to show.
   ///
-  ///  * [overlaysMask]: A mask of [SystemUiOverlay] enum values that denotes
-  ///    the overlays to show.
-  ///
-  /// Platform Specific Notes:
-  ///
-  ///   If the overlay is unsupported on the platform, enabling or disabling
-  ///   that overlay is a no-op and always return true.
+  /// If a particular overlay is unsupported on the platform, enabling or
+  /// disabling that overlay will be ignored.
   static Future<Null> setEnabledSystemUIOverlays(List<SystemUiOverlay> overlays) async {
     await PlatformMessages.invokeMethod(
       _kChannelName,
@@ -146,13 +146,16 @@ class SystemChrome {
     );
  }
 
-  /// Specifies the style of the system overlays that are visible on the
-  /// embedder (if any). The embedder may choose to ignore unsupported
-  /// overlays.
+  /// Specifies the style to use for the system overlays that are visible (if
+  /// any).
   ///
   /// This method will schedule the embedder update to be run in a microtask.
   /// Any subsequent calls to this method during the current event loop will
-  /// overwrite the pending value to be set on the embedder.
+  /// overwrite the pending value, such that only the last specified value takes
+  /// effect.
+  ///
+  /// If a particular style is not supported on the platform, selecting it will
+  /// have no effect.
   static void setSystemUIOverlayStyle(SystemUiOverlayStyle style) {
     assert(style != null);
 
@@ -163,7 +166,8 @@ class SystemChrome {
     }
 
     if (style == _latestStyle) {
-      // Trivial success; no need to queue a microtask.
+      // Trivial success: no microtask has been queued and the given style is
+      // already in effect, so no need to queue a microtask.
       return;
     }