From 8ce69a1b178ce90183950c761b3be8c2d070fba9 Mon Sep 17 00:00:00 2001 From: Michael Klimushyn Date: Tue, 12 Nov 2019 14:30:11 -0800 Subject: [PATCH 1/2] [android_intent] Add missing DartDocs --- analysis_options.yaml | 1 + packages/android_intent/CHANGELOG.md | 4 + packages/android_intent/example/lib/main.dart | 6 +- .../android_intent/lib/android_intent.dart | 43 ++++- packages/android_intent/lib/flag.dart | 158 +++++++++++++++++- packages/android_intent/pubspec.yaml | 2 +- 6 files changed, 209 insertions(+), 5 deletions(-) diff --git a/analysis_options.yaml b/analysis_options.yaml index a73c3a63e1bb..36865004700e 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -113,6 +113,7 @@ linter: - prefer_is_empty - prefer_is_not_empty - prefer_void_to_null + - public_member_api_docs # - recursive_getters # https://github.com/dart-lang/linter/issues/452 - slash_for_doc_comments - sort_constructors_first diff --git a/packages/android_intent/CHANGELOG.md b/packages/android_intent/CHANGELOG.md index a71b5e943ffa..de7b818e0d0b 100644 --- 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/example/lib/main.dart b/packages/android_intent/example/lib/main.dart index f56cffd2bd20..45de9632e975 100644 --- 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 index 9c036cf98e15..1ba8d3d15ea5 100644 --- 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 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 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 flags) { int finalValue = 0; diff --git a/packages/android_intent/lib/flag.dart b/packages/android_intent/lib/flag.dart index b4e6ed100146..e05aa6d12666 100644 --- 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 index b0248ad2a5cd..3048d5bbbdf2 100644 --- 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 homepage: https://github.com/flutter/plugins/tree/master/packages/android_intent -version: 0.3.4+5 +version: 0.3.4+6 flutter: plugin: From 110676afd09ccc601da784109127b45cb19b646f Mon Sep 17 00:00:00 2001 From: Michael Klimushyn Date: Tue, 12 Nov 2019 15:18:55 -0800 Subject: [PATCH 2/2] Add an analysis rule for DartDocs 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. --- analysis_options.yaml | 7 ++----- packages/android_intent/analysis_options.yaml | 11 +++++++++++ 2 files changed, 13 insertions(+), 5 deletions(-) create mode 100644 packages/android_intent/analysis_options.yaml diff --git a/analysis_options.yaml b/analysis_options.yaml index 36865004700e..d4a06c5b9dd4 100644 --- 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: @@ -113,12 +112,10 @@ linter: - prefer_is_empty - prefer_is_not_empty - prefer_void_to_null - - public_member_api_docs # - recursive_getters # https://github.com/dart-lang/linter/issues/452 - 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/analysis_options.yaml b/packages/android_intent/analysis_options.yaml new file mode 100644 index 000000000000..4d3c53a24cab --- /dev/null +++ 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