[google_maps_flutter] Improve README and API doc comments (#8560)

There are some inconsistencies and anachronisms in the various READMEs and in the API docs. This PR attempts to address them. - Makes sure to link to platform-specific READMEs from the main README file. - Makes the READMEs more consistent (e.g. only leaving the bare minimum quick start for the main README, and leaving all platform-specific notes to platform READMEs). - Using the more correct “Not supported on all platforms” instead of “Supported on Android only” for functionality that works on both Android and the Web. Intentionally staying vague in API docs in order to make later maintenance easier. (flutter/flutter#161948 (comment)) - Remove a doc comment from before null safety about asserting non-null. - Format the platform sections in the main README so that they’re proper lists, and so that all of them end with a link to the appropriate platform-specific README. Issues: - Fixes flutter/flutter#161954 - Related: flutter/flutter#161950, flutter/flutter#161948
flutter · Feb 24, 2025 · 4341341 · 4341341
1 parent 5498d4d
commit 4341341
Show file tree

Hide file tree

Showing 13 changed files with 100 additions and 84 deletions.
diff --git a/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md
@@ -1,5 +1,6 @@
-## NEXT
+## 2.10.1
 
+* Updates READMEs and API docs.
 * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4.
 
 ## 2.10.0

diff --git a/packages/google_maps_flutter/google_maps_flutter/README.md b/packages/google_maps_flutter/google_maps_flutter/README.md
@@ -12,6 +12,15 @@ A Flutter plugin that provides a [Google Maps](https://developers.google.com/map
 
 [web-support]: https://docs.flutter.dev/reference/supported-platforms
 
+**Important:** Not all functionality is supported on all platforms.
+To check details, please read the README files
+of the endorsed platform packages:
+
+* [`google_maps_flutter_android` README](https://pub.dev/packages/google_maps_flutter_android)
+* [`google_maps_flutter_ios` README](https://pub.dev/packages/google_maps_flutter_ios)
+* [`google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web)
+
+
 ## Getting Started
 
 * Get an API key at <https://cloud.google.com/maps-platform/>.
@@ -30,86 +39,72 @@ For more details, see [Getting started with Google Maps Platform](https://develo
 
 ### Android
 
-1. Set the `minSdkVersion` in `android/app/build.gradle`:
-
-```groovy
-android {
-    defaultConfig {
-        minSdkVersion 20
-    }
-}
-```
-
-This means that app will only be available for users that run Android SDK 20 or higher.
-
-2. Specify your API key in the application manifest `android/app/src/main/AndroidManifest.xml`:
-
-```xml
-<manifest ...
-  <application ...
-    <meta-data android:name="com.google.android.geo.API_KEY"
-               android:value="YOUR KEY HERE"/>
-```
-
-#### Display Mode
+1. Specify your API key in the application manifest `android/app/src/main/AndroidManifest.xml`:
 
-The Android implementation supports multiple
-[platform view display modes](https://docs.flutter.dev/platform-integration/android/platform-views).
-For details, see [the Android README](https://pub.dev/packages/google_maps_flutter_android#display-mode).
+   ```xml
+   <manifest ...
+     <application ...
+       <meta-data android:name="com.google.android.geo.API_KEY"
+                  android:value="YOUR KEY HERE"/>
+   ```
 
-#### Cloud-based map styling
-
-Cloud-based map styling works on Android only if `AndroidMapRenderer.latest` map renderer has been initialized.
-For details, see [the Android README](https://pub.dev/packages/google_maps_flutter_android#map-renderer).
+2. Read about Android-specific features and limitations in the
+   [`google_maps_flutter_android` README](https://pub.dev/packages/google_maps_flutter_android).
 
 ### iOS
 
-To set up, specify your API key in the application delegate `ios/Runner/AppDelegate.m`:
-
-```objectivec
-#include "AppDelegate.h"
-#include "GeneratedPluginRegistrant.h"
-#import "GoogleMaps/GoogleMaps.h"
-
-@implementation AppDelegate
-
-- (BOOL)application:(UIApplication *)application
-    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
-  [GMSServices provideAPIKey:@"YOUR KEY HERE"];
-  [GeneratedPluginRegistrant registerWithRegistry:self];
-  return [super application:application didFinishLaunchingWithOptions:launchOptions];
-}
-@end
-```
-
-Or in your swift code, specify your API key in the application delegate `ios/Runner/AppDelegate.swift`:
-
-```swift
-import UIKit
-import Flutter
-import GoogleMaps
-
-@UIApplicationMain
-@objc class AppDelegate: FlutterAppDelegate {
-  override func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
-  ) -> Bool {
-    GMSServices.provideAPIKey("YOUR KEY HERE")
-    GeneratedPluginRegistrant.register(with: self)
-    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-  }
-}
-```
+1. Specify your API key in the application delegate `ios/Runner/AppDelegate.m`:
+
+   ```objectivec
+   #include "AppDelegate.h"
+   #include "GeneratedPluginRegistrant.h"
+   #import "GoogleMaps/GoogleMaps.h"
+
+   @implementation AppDelegate
+
+   - (BOOL)application:(UIApplication *)application
+       didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+     [GMSServices provideAPIKey:@"YOUR KEY HERE"];
+     [GeneratedPluginRegistrant registerWithRegistry:self];
+     return [super application:application didFinishLaunchingWithOptions:launchOptions];
+   }
+   @end
+   ```
+
+   Or in your Swift code, specify your API key
+   in the application delegate `ios/Runner/AppDelegate.swift`:
+
+   ```swift
+   import UIKit
+   import Flutter
+   import GoogleMaps
+
+   @UIApplicationMain
+   @objc class AppDelegate: FlutterAppDelegate {
+     override func application(
+       _ application: UIApplication,
+       didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
+     ) -> Bool {
+       GMSServices.provideAPIKey("YOUR KEY HERE")
+       GeneratedPluginRegistrant.register(with: self)
+       return super.application(application, didFinishLaunchingWithOptions: launchOptions)
+     }
+   }
+   ```
+
+2. Read about iOS-specific features and limitations in the
+   [`google_maps_flutter_ios` README](https://pub.dev/packages/google_maps_flutter_ios).
 
 ### Web
 
-You'll need to modify the `web/index.html` file of your Flutter Web application
-to include the Google Maps JS SDK.
+1. Add the following to the `<head>` section of `web/index.html`:
+
+   ```html
+   <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY"></script>
+   ```
 
-Check [the `google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web)
-for the latest information on how to prepare your App to use Google Maps on the
-web.
+2. Read about iOS-specific features and limitations in the
+   [`google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web).
 
 ### All
 

diff --git a/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart b/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart
@@ -87,7 +87,7 @@ class AndroidGoogleMapsFlutter {
 class GoogleMap extends StatefulWidget {
   /// Creates a widget displaying data from Google Maps services.
   ///
-  /// [AssertionError] will be thrown if [initialCameraPosition] is null;
+  /// The map's camera will start centered on [initialCameraPosition].
   const GoogleMap({
     super.key,
     required this.initialCameraPosition,
@@ -110,8 +110,6 @@ class GoogleMap extends StatefulWidget {
     this.myLocationEnabled = false,
     this.myLocationButtonEnabled = true,
     this.layoutDirection,
-
-    /// If no padding is specified default padding will be 0.
     this.padding = EdgeInsets.zero,
     this.indoorViewEnabled = false,
     this.trafficEnabled = false,
@@ -202,6 +200,8 @@ class GoogleMap extends StatefulWidget {
   final bool fortyFiveDegreeImageryEnabled;
 
   /// Padding to be set on map. See https://developers.google.com/maps/documentation/android-sdk/map#map_padding for more details.
+  ///
+  /// If no padding is specified, the default padding is 0.
   final EdgeInsets padding;
 
   /// Markers to be placed on the map.
@@ -223,6 +223,9 @@ class GoogleMap extends StatefulWidget {
   final Set<TileOverlay> tileOverlays;
 
   /// Cluster Managers to be initialized for the map.
+  ///
+  /// On the web, an extra step is required to enable clusters.
+  /// See https://pub.dev/packages/google_maps_flutter_web.
   final Set<ClusterManager> clusterManagers;
 
   /// Called when the camera starts moving.
@@ -261,6 +264,8 @@ class GoogleMap extends StatefulWidget {
   /// * The My Location button animates to focus on the user's current location
   /// if the user's location is currently known.
   ///
+  /// This feature is not present in the Google Maps SDK for the web.
+  ///
   /// Enabling this feature requires adding location permissions to both native
   /// platforms of your app.
   /// * On Android add either

diff --git a/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml
@@ -2,7 +2,7 @@ name: google_maps_flutter
 description: A Flutter plugin for integrating Google Maps in iOS and Android applications.
 repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22
-version: 2.10.0
+version: 2.10.1
 
 environment:
   sdk: ^3.4.0

diff --git a/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 2.14.13
+
+* Updates READMEs and API docs.
+
 ## 2.14.12
 
 * Updates androidx.annotation:annotation to 1.9.1.

diff --git a/packages/google_maps_flutter/google_maps_flutter_android/README.md b/packages/google_maps_flutter/google_maps_flutter_android/README.md
@@ -39,7 +39,7 @@ void main() {
 
 ### Texture Layer Hybrid Composition
 
-This is the the current default mode and corresponds to `useAndroidViewSurface = false`.
+This is the current default mode and corresponds to `useAndroidViewSurface = false`.
 This mode is more performant than Hybrid Composition and we recommend that you use this mode.
 
 ### Hybrid Composition
@@ -78,6 +78,10 @@ Google Play the latest renderer will not be available and the legacy renderer wi
 WARNING: `AndroidMapRenderer.legacy` is known to crash apps and is no longer supported by the Google Maps team
 and therefore cannot be supported by the Flutter team.
 
+### Cloud-based map styling
+
+Cloud-based map styling is not supported with the `AndroidMapRenderer.legacy` renderer.
+
 ## Supported Heatmap Options
 
 | Field                        | Supported |

diff --git a/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml
@@ -2,7 +2,7 @@ name: google_maps_flutter_android
 description: Android implementation of the google_maps_flutter plugin.
 repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter_android
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22
-version: 2.14.12
+version: 2.14.13
 
 environment:
   sdk: ^3.5.0

diff --git a/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md
@@ -1,6 +1,11 @@
+## 2.11.1
+
+* Updates READMEs and API docs.
+
 ## 2.11.0
 
 * Adds support for animating the camera with a duration.
+* Updates READMEs and API docs.
 
 ## 2.10.0
 

diff --git a/...es/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart b/...es/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart
@@ -66,7 +66,7 @@ class Polyline implements MapsObject<Polyline> {
   /// polyline except the start and end vertices. See [JointType] for supported joint types. The default value is
   /// mitered.
   ///
-  /// Supported on Android only.
+  /// Not supported on all platforms.
   final JointType jointType;
 
   /// The stroke pattern for the polyline.
@@ -86,14 +86,14 @@ class Polyline implements MapsObject<Polyline> {
   ///
   /// The default start cap is ButtCap.
   ///
-  /// Supported on Android only.
+  /// Not supported on all platforms.
   final Cap startCap;
 
   /// The cap at the end vertex of the polyline.
   ///
   /// The default end cap is ButtCap.
   ///
-  /// Supported on Android only.
+  /// Not supported on all platforms.
   final Cap endCap;
 
   /// True if the polyline is visible.

diff --git a/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml
@@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/google_maps_f
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 2.11.0
+version: 2.11.1
 
 environment:
   sdk: ^3.4.0

diff --git a/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md
@@ -1,5 +1,6 @@
-## NEXT
+## 0.5.10+1
 
+* Updates READMEs and API docs.
 * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4.
 
 ## 0.5.10

diff --git a/packages/google_maps_flutter/google_maps_flutter_web/README.md b/packages/google_maps_flutter/google_maps_flutter_web/README.md
@@ -64,6 +64,7 @@ If you need marker clustering support, modify the <head> tag to load the [js-mar
 ```
 
 ## Heatmaps
+
 To use heatmaps, add `&libraries=visualization` to the end of the URL. See [the documentation](https://developers.google.com/maps/documentation/javascript/libraries) for more information.
 
 ## Limitations of the web version

diff --git a/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml
@@ -2,7 +2,7 @@ name: google_maps_flutter_web
 description: Web platform implementation of google_maps_flutter
 repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter_web
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22
-version: 0.5.10
+version: 0.5.10+1
 
 environment:
   sdk: ^3.4.0
-Original file line number
+Diff line change
@@ Expand Up @@
     ```
     ## Heatmaps
     To use heatmaps, add `&libraries=visualization` to the end of the URL. See [the documentation](https://developers.google.com/maps/documentation/javascript/libraries) for more information.
     ## Limitations of the web version
@@ Expand Down @@