[google_maps_flutter] Add documentation (flutter#2303)

bparrishMines · Park Sung Min · commit 4fc955e78121 · 2019-12-17T23:03:28.000+09:00
diff --git a/packages/google_maps_flutter/CHANGELOG.md b/packages/google_maps_flutter/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 0.5.21+13
+
+* Add documentation.
+
 ## 0.5.21+12
 
 * Update driver tests in the example app to e2e tests.
diff --git a/packages/google_maps_flutter/analysis_options.yaml b/packages/google_maps_flutter/analysis_options.yaml
diff --git a/packages/google_maps_flutter/example/lib/animate_camera.dart b/packages/google_maps_flutter/example/lib/animate_camera.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 
diff --git a/packages/google_maps_flutter/example/lib/main.dart b/packages/google_maps_flutter/example/lib/main.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'animate_camera.dart';
 import 'map_click.dart';
diff --git a/packages/google_maps_flutter/example/lib/map_click.dart b/packages/google_maps_flutter/example/lib/map_click.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:flutter/widgets.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
diff --git a/packages/google_maps_flutter/example/lib/map_coordinates.dart b/packages/google_maps_flutter/example/lib/map_coordinates.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:flutter/widgets.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
diff --git a/packages/google_maps_flutter/example/lib/map_ui.dart b/packages/google_maps_flutter/example/lib/map_ui.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 import 'package:flutter/services.dart' show rootBundle;
diff --git a/packages/google_maps_flutter/example/lib/marker_icons.dart b/packages/google_maps_flutter/example/lib/marker_icons.dart
@@ -2,6 +2,9 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+// ignore_for_file: unawaited_futures
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 
diff --git a/packages/google_maps_flutter/example/lib/move_camera.dart b/packages/google_maps_flutter/example/lib/move_camera.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 
diff --git a/packages/google_maps_flutter/example/lib/padding.dart b/packages/google_maps_flutter/example/lib/padding.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 import 'page.dart';
diff --git a/packages/google_maps_flutter/example/lib/page.dart b/packages/google_maps_flutter/example/lib/page.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 
 abstract class Page extends StatelessWidget {
diff --git a/packages/google_maps_flutter/example/lib/place_circle.dart b/packages/google_maps_flutter/example/lib/place_circle.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 
diff --git a/packages/google_maps_flutter/example/lib/place_marker.dart b/packages/google_maps_flutter/example/lib/place_marker.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'dart:async';
 import 'dart:math';
 import 'dart:ui';
diff --git a/packages/google_maps_flutter/example/lib/place_polygon.dart b/packages/google_maps_flutter/example/lib/place_polygon.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/material.dart';
 import 'package:google_maps_flutter/google_maps_flutter.dart';
 
diff --git a/packages/google_maps_flutter/example/lib/place_polyline.dart b/packages/google_maps_flutter/example/lib/place_polyline.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'dart:io' show Platform;
 
 import 'package:flutter/material.dart';
diff --git a/packages/google_maps_flutter/example/lib/scrolling_map.dart b/packages/google_maps_flutter/example/lib/scrolling_map.dart
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+// ignore_for_file: public_member_api_docs
+
 import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
diff --git a/packages/google_maps_flutter/example/test_driver/google_maps_e2e_test.dart b/packages/google_maps_flutter/example/test_driver/google_maps_e2e_test.dart
@@ -10,6 +10,6 @@ Future<void> main() async {
   final FlutterDriver driver = await FlutterDriver.connect();
   final String result =
       await driver.requestData(null, timeout: const Duration(minutes: 1));
-  driver.close();
+  await driver.close();
   exit(result == 'pass' ? 0 : 1);
 }
diff --git a/packages/google_maps_flutter/lib/src/bitmap.dart b/packages/google_maps_flutter/lib/src/bitmap.dart
@@ -10,15 +10,34 @@ part of google_maps_flutter;
 class BitmapDescriptor {
   const BitmapDescriptor._(this._json);
 
+  /// Convenience hue value representing red.
   static const double hueRed = 0.0;
+
+  /// Convenience hue value representing orange.
   static const double hueOrange = 30.0;
+
+  /// Convenience hue value representing yellow.
   static const double hueYellow = 60.0;
+
+  /// Convenience hue value representing green.
   static const double hueGreen = 120.0;
+
+  /// Convenience hue value representing cyan.
   static const double hueCyan = 180.0;
+
+  /// Convenience hue value representing azure.
   static const double hueAzure = 210.0;
+
+  /// Convenience hue value representing blue.
   static const double hueBlue = 240.0;
+
+  /// Convenience hue value representing violet.
   static const double hueViolet = 270.0;
+
+  /// Convenience hue value representing magenta.
   static const double hueMagenta = 300.0;
+
+  /// Convenience hue value representing rose.
   static const double hueRose = 330.0;
 
   /// Creates a BitmapDescriptor that refers to the default marker image.
diff --git a/packages/google_maps_flutter/lib/src/camera.dart b/packages/google_maps_flutter/lib/src/camera.dart
@@ -4,10 +4,15 @@
 
 part of google_maps_flutter;
 
-/// The position of the map "camera", the view point from which the world is
-/// shown in the map view. Aggregates the camera's [target] geographical
-/// location, its [zoom] level, [tilt] angle, and [bearing].
+/// The position of the map "camera", the view point from which the world is shown in the map view.
+///
+/// Aggregates the camera's [target] geographical location, its [zoom] level,
+/// [tilt] angle, and [bearing].
 class CameraPosition {
+  /// Creates a immutable representation of the [GoogleMap] camera.
+  ///
+  /// [AssertionError] is thrown if [bearing], [target], [tilt], or [zoom] are
+  /// null.
   const CameraPosition({
     this.bearing = 0.0,
     @required this.target,
@@ -51,13 +56,19 @@ class CameraPosition {
   /// will be silently clamped to the supported range.
   final double zoom;
 
+  /// Serializes [CameraPosition].
+  ///
+  /// Mainly for internal use when calling [CameraUpdate.newCameraPosition].
   dynamic toMap() => <String, dynamic>{
         'bearing': bearing,
         'target': target._toJson(),
         'tilt': tilt,
         'zoom': zoom,
       };
 
+  /// Deserializes [CameraPosition] from a map.
+  ///
+  /// Mainly for internal use.
   static CameraPosition fromMap(dynamic json) {
     if (json == null) {
       return null;
diff --git a/packages/google_maps_flutter/lib/src/circle.dart b/packages/google_maps_flutter/lib/src/circle.dart
@@ -9,6 +9,7 @@ part of google_maps_flutter;
 /// This does not have to be globally unique, only unique among the list.
 @immutable
 class CircleId {
+  /// Creates an immutable identifier for a [Circle].
   CircleId(this.value) : assert(value != null);
 
   /// value of the [CircleId].
@@ -34,6 +35,7 @@ class CircleId {
 /// Draws a circle on the map.
 @immutable
 class Circle {
+  /// Creates an immutable representation of a [Circle] to draw on [GoogleMap].
   const Circle({
     @required this.circleId,
     this.consumeTapEvents = false,
diff --git a/packages/google_maps_flutter/lib/src/controller.dart b/packages/google_maps_flutter/lib/src/controller.dart
@@ -14,6 +14,10 @@ class GoogleMapController {
     channel.setMethodCallHandler(_handleMethodCall);
   }
 
+  /// Initialize control of a [GoogleMap] with [id].
+  ///
+  /// Mainly for internal use when instantiating a [GoogleMapController] passed
+  /// in [GoogleMap.onMapCreated] callback.
   static Future<GoogleMapController> init(
     int id,
     CameraPosition initialCameraPosition,
@@ -30,6 +34,9 @@ class GoogleMapController {
     );
   }
 
+  /// Used to communicate with the native platform.
+  ///
+  /// Accessible only for testing.
   @visibleForTesting
   final MethodChannel channel;
 
diff --git a/packages/google_maps_flutter/lib/src/google_map.dart b/packages/google_maps_flutter/lib/src/google_map.dart
@@ -4,6 +4,10 @@
 
 part of google_maps_flutter;
 
+/// Callback method for when the map is ready to be used.
+///
+/// Pass to [GoogleMap.onMapCreated] to receive a [GoogleMapController] when the
+/// map is created.
 typedef void MapCreatedCallback(GoogleMapController controller);
 
 /// Callback that receives updates to the camera position.
@@ -14,7 +18,11 @@ typedef void MapCreatedCallback(GoogleMapController controller);
 /// This is used in [GoogleMap.onCameraMove].
 typedef void CameraPositionCallback(CameraPosition position);
 
+/// A widget which displays a map with data obtained from the Google Maps service.
 class GoogleMap extends StatefulWidget {
+  /// Creates a widget displaying data from Google Maps services.
+  ///
+  /// [AssertionError] will be thrown if [initialCameraPosition] is null;
   const GoogleMap({
     Key key,
     @required this.initialCameraPosition,
@@ -48,6 +56,9 @@ class GoogleMap extends StatefulWidget {
   })  : assert(initialCameraPosition != null),
         super(key: key);
 
+  /// Callback method for when the map is ready to be used.
+  ///
+  /// Used to receive a [GoogleMapController] for this [GoogleMap].
   final MapCreatedCallback onMapCreated;
 
   /// The initial position of the map's camera.
@@ -179,6 +190,7 @@ class GoogleMap extends StatefulWidget {
   /// were not claimed by any other gesture recognizer.
   final Set<Factory<OneSequenceGestureRecognizer>> gestureRecognizers;
 
+  /// Creates a [State] for this [GoogleMap].
   @override
   State createState() => _GoogleMapState();
 }
@@ -253,33 +265,38 @@ class _GoogleMapState extends State<GoogleMap> {
       return;
     }
     final GoogleMapController controller = await _controller.future;
+    // ignore: unawaited_futures
     controller._updateMapOptions(updates);
     _googleMapOptions = newOptions;
   }
 
   void _updateMarkers() async {
     final GoogleMapController controller = await _controller.future;
+    // ignore: unawaited_futures
     controller._updateMarkers(
         _MarkerUpdates.from(_markers.values.toSet(), widget.markers));
     _markers = _keyByMarkerId(widget.markers);
   }
 
   void _updatePolygons() async {
     final GoogleMapController controller = await _controller.future;
+    // ignore: unawaited_futures
     controller._updatePolygons(
         _PolygonUpdates.from(_polygons.values.toSet(), widget.polygons));
     _polygons = _keyByPolygonId(widget.polygons);
   }
 
   void _updatePolylines() async {
     final GoogleMapController controller = await _controller.future;
+    // ignore: unawaited_futures
     controller._updatePolylines(
         _PolylineUpdates.from(_polylines.values.toSet(), widget.polylines));
     _polylines = _keyByPolylineId(widget.polylines);
   }
 
   void _updateCircles() async {
     final GoogleMapController controller = await _controller.future;
+    // ignore: unawaited_futures
     controller._updateCircles(
         _CircleUpdates.from(_circles.values.toSet(), widget.circles));
     _circles = _keyByCircleId(widget.circles);
diff --git a/packages/google_maps_flutter/lib/src/location.dart b/packages/google_maps_flutter/lib/src/location.dart
@@ -95,6 +95,7 @@ class LatLngBounds {
     }
   }
 
+  /// Converts a list to [LatLngBounds].
   @visibleForTesting
   static LatLngBounds fromList(dynamic json) {
     if (json == null) {
diff --git a/packages/google_maps_flutter/lib/src/marker.dart b/packages/google_maps_flutter/lib/src/marker.dart
@@ -13,6 +13,7 @@ dynamic _offsetToJson(Offset offset) {
 
 /// Text labels for a [Marker] info window.
 class InfoWindow {
+  /// Creates an immutable representation of a label on for [Marker].
   const InfoWindow({
     this.title,
     this.snippet,
@@ -100,6 +101,7 @@ class InfoWindow {
 /// This does not have to be globally unique, only unique among the list.
 @immutable
 class MarkerId {
+  /// Creates an immutable identifier for a [Marker].
   MarkerId(this.value) : assert(value != null);
 
   /// value of the [MarkerId].
@@ -146,6 +148,8 @@ class Marker {
   /// * has an axis-aligned icon; [rotation] is 0.0
   /// * is visible; [visible] is true
   /// * is placed at the base of the drawing order; [zIndex] is 0.0
+  /// * reports [onTap] events
+  /// * reports [onDragEnd] events
   const Marker({
     @required this.markerId,
     this.alpha = 1.0,
@@ -217,6 +221,7 @@ class Marker {
   /// Callbacks to receive tap events for markers placed on this map.
   final VoidCallback onTap;
 
+  /// Signature reporting the new [LatLng] at the end of a drag event.
   final ValueChanged<LatLng> onDragEnd;
 
   /// Creates a new [Marker] object whose values are the same as this instance,
diff --git a/packages/google_maps_flutter/lib/src/pattern_item.dart b/packages/google_maps_flutter/lib/src/pattern_item.dart
@@ -9,6 +9,7 @@ part of google_maps_flutter;
 class PatternItem {
   const PatternItem._(this._json);
 
+  /// A dot used in the stroke pattern for a [Polyline].
   static const PatternItem dot = PatternItem._(<dynamic>['dot']);
 
   /// A dash used in the stroke pattern for a [Polyline].
diff --git a/packages/google_maps_flutter/lib/src/polygon.dart b/packages/google_maps_flutter/lib/src/polygon.dart
diff --git a/packages/google_maps_flutter/lib/src/polyline.dart b/packages/google_maps_flutter/lib/src/polyline.dart
diff --git a/packages/google_maps_flutter/lib/src/screen_coordinate.dart b/packages/google_maps_flutter/lib/src/screen_coordinate.dart
diff --git a/packages/google_maps_flutter/lib/src/ui.dart b/packages/google_maps_flutter/lib/src/ui.dart
diff --git a/packages/google_maps_flutter/pubspec.yaml b/packages/google_maps_flutter/pubspec.yaml
