[android_intent] Add missing DartDocs (flutter#2268)

Also adds a rule just for `android_intent` that makes sure that there are no undocumented public members. This will prevent the DartDocs from regressing. Also updates the main repo's analysis options to migrate from some deprecated options. If/when all the plugins have their DartDocs updated this package-specific `analysis_options.yaml` should be removed, and the DartDoc rule should be moved up to the top level.
mormih · Nov 13, 2019 · 35e984f · 35e984f
1 parent 7d7be76
commit 35e984f
Show file tree

Hide file tree

Showing 7 changed files with 221 additions and 9 deletions.
diff --git a/analysis_options.yaml b/analysis_options.yaml
@@ -12,9 +12,8 @@
 
 analyzer:
   language:
-    enableStrictCallChecks: true
-    enableSuperMixins: true
-    enableAssertInitializer: true
+    strict-inference: true
+    strict-raw-types: true
   strong-mode:
     implicit-dynamic: false
   errors:
@@ -117,7 +116,6 @@ linter:
     - slash_for_doc_comments
     - sort_constructors_first
     - sort_unnamed_constructors_first
-    - super_goes_last
     # - type_annotate_public_apis # subset of always_specify_types
     - type_init_formals
     # - unawaited_futures # https://github.com/flutter/flutter/issues/5793

diff --git a/packages/android_intent/CHANGELOG.md b/packages/android_intent/CHANGELOG.md
@@ -1,3 +1,7 @@
+##  0.3.4+6
+
+* Add missing DartDocs for public members.
+
 ##  0.3.4+5
 
 * Remove AndroidX warning.

diff --git a/packages/android_intent/analysis_options.yaml b/packages/android_intent/analysis_options.yaml
@@ -0,0 +1,11 @@
+# This exists to add a lint for missing API docs just on this specific package,
+# since not all packages have coverage for all their public members yet and
+# adding it in would be non-trivial. `public_member_api_docs` should be applied
+# to new packages going forward, and ideally the main `analysis_options.yaml`
+# file as soon as possible.
+
+include: ../../analysis_options.yaml
+
+linter:
+  rules:
+    - public_member_api_docs
diff --git a/packages/android_intent/example/lib/main.dart b/packages/android_intent/example/lib/main.dart
@@ -11,6 +11,7 @@ void main() {
   runApp(MyApp());
 }
 
+/// A sample app for launching intents.
 class MyApp extends StatelessWidget {
   // This widget is the root of your application.
   @override
@@ -29,6 +30,7 @@ class MyApp extends StatelessWidget {
   }
 }
 
+/// Holds the different intent widgets.
 class MyHomePage extends StatelessWidget {
   void _createAlarm() {
     final AndroidIntent intent = const AndroidIntent(
@@ -80,9 +82,11 @@ class MyHomePage extends StatelessWidget {
   }
 }
 
+/// Launches intents to specific Android activities.
 class ExplicitIntentsWidget extends StatelessWidget {
-  const ExplicitIntentsWidget();
+  const ExplicitIntentsWidget(); // ignore: public_member_api_docs
 
+  // ignore: public_member_api_docs
   static const String routeName = "/explicitIntents";
 
   void _openGoogleMapsStreetView() {

diff --git a/packages/android_intent/lib/android_intent.dart b/packages/android_intent/lib/android_intent.dart
@@ -8,9 +8,13 @@ import 'package:flutter/services.dart';
 import 'package:meta/meta.dart';
 import 'package:platform/platform.dart';
 
-const String kChannelName = 'plugins.flutter.io/android_intent';
+const String _kChannelName = 'plugins.flutter.io/android_intent';
 
 /// Flutter plugin for launching arbitrary Android Intents.
+///
+/// See [the official Android
+/// documentation](https://developer.android.com/reference/android/content/Intent.html)
+/// for more information on how to use Intents.
 class AndroidIntent {
   /// Builds an Android intent with the following parameters
   /// [action] refers to the action parameter of the intent.
@@ -33,9 +37,11 @@ class AndroidIntent {
     this.componentName,
     Platform platform,
   })  : assert(action != null),
-        _channel = const MethodChannel(kChannelName),
+        _channel = const MethodChannel(_kChannelName),
         _platform = platform ?? const LocalPlatform();
 
+  /// This constructor is only exposed for unit testing. Do not rely on this in
+  /// app code, it may break without warning.
   @visibleForTesting
   AndroidIntent.private({
     @required this.action,
@@ -50,12 +56,43 @@ class AndroidIntent {
   })  : _channel = channel,
         _platform = platform;
 
+  /// This is the general verb that the intent should attempt to do. This
+  /// includes constants like `ACTION_VIEW`.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#intent-structure.
   final String action;
+
+  /// Constants that can be set on an intent to tweak how it is finally handled.
+  /// Some of the constants are mirrored to Dart via [Flag].
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#setFlags(int).
   final List<int> flags;
+
+  /// An optional additional constant qualifying the given [action].
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#intent-structure.
   final String category;
+
+  /// The Uri that the [action] is pointed towards.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#intent-structure.
   final String data;
+
+  /// The equivalent of `extras`, a generic `Bundle` of data that the Intent can
+  /// carry. This is a slot for extraneous data that the listener may use.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#intent-structure.
   final Map<String, dynamic> arguments;
+
+  /// Sets the [data] to only resolve within this given package.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#setPackage(java.lang.String).
   final String package;
+
+  /// Set the exact `ComponentName` that should handle the intent. If this is
+  /// set [package] should also be non-null.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#setComponent(android.content.ComponentName).
   final String componentName;
   final MethodChannel _channel;
   final Platform _platform;
@@ -65,6 +102,8 @@ class AndroidIntent {
     return x != 0 && ((x & (x - 1)) == 0);
   }
 
+  /// This method is just visible for unit testing and should not be relied on.
+  /// Its method signature may change at any time.
   @visibleForTesting
   int convertFlags(List<int> flags) {
     int finalValue = 0;

diff --git a/packages/android_intent/lib/flag.dart b/packages/android_intent/lib/flag.dart
@@ -1,37 +1,193 @@
-// flag values from https://developer.android.com/reference/android/content/Intent.html
+/// Special flags that can be set on an intent to control how it is handled.
+///
+/// See
+/// https://developer.android.com/reference/android/content/Intent.html#setFlags(int)
+/// for the official documentation on Intent flags. The constants here mirror
+/// the existing [android.content.Intent] ones.
 class Flag {
+  /// Specifies how an activity should be launched. Generally set by the system
+  /// in conjunction with SINGLE_TASK.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_BROUGHT_TO_FRONT.
   static const int FLAG_ACTIVITY_BROUGHT_TO_FRONT = 4194304;
+
+  /// Causes any existing tasks associated with the activity to be cleared.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_CLEAR_TASK
   static const int FLAG_ACTIVITY_CLEAR_TASK = 32768;
+
+  /// Closes any activities on top of this activity and brings it to the front,
+  /// if it's currently running.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_CLEAR_TOP
   static const int FLAG_ACTIVITY_CLEAR_TOP = 67108864;
+
+  /// @deprecated Use [FLAG_ACTIVITY_NEW_DOCUMENT] instead when on API 21 or above.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET
+  @deprecated
   static const int FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET = 524288;
+
+  /// Keeps the activity from being listed with other recently launched
+  /// activities.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS
   static const int FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS = 8388608;
+
+  /// Forwards the result from this activity to the existing one.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_FORWARD_RESULT
   static const int FLAG_ACTIVITY_FORWARD_RESULT = 33554432;
+
+  /// Generally set by the system if the activity is being launched from
+  /// history.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY
   static const int FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY = 1048576;
+
+  /// Used in split-screen mode to set the launched activity adjacent to the
+  /// launcher.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_LAUNCH_ADJACENT
   static const int FLAG_ACTIVITY_LAUNCH_ADJACENT = 4096;
+
+  /// Used in split-screen mode to set the launched activity adjacent to the
+  /// launcher.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_MATCH_EXTERNAL
   static const int FLAG_ACTIVITY_MATCH_EXTERNAL = 2048;
+
+  /// Creates and launches the activity into a new task. Should always be
+  /// combined with [FLAG_ACTIVITY_NEW_DOCUMENT] or [FLAG_ACTIVITY_NEW_TASK].
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_MULTIPLE_TASK.
   static const int FLAG_ACTIVITY_MULTIPLE_TASK = 134217728;
+
+  /// Opens a document into a new task rooted in this activity.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_NEW_DOCUMENT.
   static const int FLAG_ACTIVITY_NEW_DOCUMENT = 524288;
+
+  /// The launched activity starts a new task on the activity stack.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_NEW_TASK.
   static const int FLAG_ACTIVITY_NEW_TASK = 268435456;
+
+  /// Prevents the system from playing an activity transition animation when
+  /// launching this.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_NO_ANIMATION.
   static const int FLAG_ACTIVITY_NO_ANIMATION = 65536;
+
+  /// Does not keep the launched activity in history.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_NO_HISTORY.
   static const int FLAG_ACTIVITY_NO_HISTORY = 1073741824;
+
+  /// Prevents a typical callback from occuring when the activity is paused.
+  ///
+  /// https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_NO_USER_ACTION
   static const int FLAG_ACTIVITY_NO_USER_ACTION = 262144;
+
+  /// Uses the previous activity as top when applicable.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_PREVIOUS_IS_TOP.
   static const int FLAG_ACTIVITY_PREVIOUS_IS_TOP = 16777216;
+
+  /// Brings any already instances of this activity to the front.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_REORDER_TO_FRONT.
   static const int FLAG_ACTIVITY_REORDER_TO_FRONT = 131072;
+
+  /// Launches the activity in a way that resets the task in some cases.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED.
   static const int FLAG_ACTIVITY_RESET_TASK_IF_NEEDED = 2097152;
+
+  /// Keeps an entry in recent tasks. Used with [FLAG_ACTIVITY_NEW_DOCUMENT].
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_RETAIN_IN_RECENTS.
   static const int FLAG_ACTIVITY_RETAIN_IN_RECENTS = 8192;
+
+  /// Will not re-launch the activity if it is already at the top of the history
+  /// stack.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_SINGLE_TOP.
   static const int FLAG_ACTIVITY_SINGLE_TOP = 536870912;
+
+  /// Places the activity on top of the home task. Must be used with
+  /// [FLAG_ACTIVITY_NEW_TASK].
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_ACTIVITY_TASK_ON_HOME.
   static const int FLAG_ACTIVITY_TASK_ON_HOME = 16384;
+
+  /// Prints debug logs while the intent is resolving.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_DEBUG_LOG_RESOLUTION.
   static const int FLAG_DEBUG_LOG_RESOLUTION = 8;
+
+  /// Does not match to any stopped components.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_EXCLUDE_STOPPED_PACKAGES.
   static const int FLAG_EXCLUDE_STOPPED_PACKAGES = 16;
+
+  /// Can be set by the caller to flag the intent as not being launched directly
+  /// by the user.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_FROM_BACKGROUND.
   static const int FLAG_FROM_BACKGROUND = 4;
+
+  /// Will persist the URI permision across device reboots.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_GRANT_PERSISTABLE_URI_PERMISSION.
   static const int FLAG_GRANT_PERSISTABLE_URI_PERMISSION = 64;
+
+  /// Applies the URI permission grant based on prefix matching.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_GRANT_PREFIX_URI_PERMISSION.
   static const int FLAG_GRANT_PREFIX_URI_PERMISSION = 128;
+
+  /// Grants the intent listener permission to read extra data from the Intent's
+  /// URI.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_GRANT_READ_URI_PERMISSION.
   static const int FLAG_GRANT_READ_URI_PERMISSION = 1;
+
+  /// Grants the intent listener permission to write extra data from the
+  /// Intent's URI.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_GRANT_WRITE_URI_PERMISSION.
   static const int FLAG_GRANT_WRITE_URI_PERMISSION = 2;
+
+  /// Always matches stopped components. This is the default behavior.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_INCLUDE_STOPPED_PACKAGES.
   static const int FLAG_INCLUDE_STOPPED_PACKAGES = 32;
+
+  /// Allows the listener to run at a high priority.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_RECEIVER_FOREGROUND.
   static const int FLAG_RECEIVER_FOREGROUND = 268435456;
+
+  /// Doesn't allow listeners to cancel the broadcast.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_RECEIVER_NO_ABORT.
   static const int FLAG_RECEIVER_NO_ABORT = 134217728;
+
+  /// Only allows registered receivers to listen for the intent.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_RECEIVER_REGISTERED_ONLY.
   static const int FLAG_RECEIVER_REGISTERED_ONLY = 1073741824;
+
+  /// Will drop any pending broadcasts of this intent in favor of the newest
+  /// one.
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_RECEIVER_REPLACE_PENDING.
   static const int FLAG_RECEIVER_REPLACE_PENDING = 536870912;
+
+  /// Instant Apps will be able to listen for the intent (not the default
+  /// behavior).
+  ///
+  /// See https://developer.android.com/reference/android/content/Intent.html#FLAG_RECEIVER_VISIBLE_TO_INSTANT_APPS.
   static const int FLAG_RECEIVER_VISIBLE_TO_INSTANT_APPS = 2097152;
 }
diff --git a/packages/android_intent/pubspec.yaml b/packages/android_intent/pubspec.yaml
@@ -2,7 +2,7 @@ name: android_intent
 description: Flutter plugin for launching Android Intents. Not supported on iOS.
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/android_intent
-version: 0.3.4+5
+version: 0.3.4+6
 
 flutter:
   plugin: