documentation updates (#490)

flutter_local_notifications/README.md

@@ -39,7 +39,7 @@ A cross platform plugin for displaying local notifications.
 * [Android] Group notifications
 * [Android] Show progress notifications
 * [Android] Configure notification visibility on the lockscreen
-* [iOS] Delay requesting notification permission
+* [iOS] Request notification permissions when needed (e.g. in response to user turning on a setting)
 * [iOS] Customise the permissions to be requested around displaying notifications
 
 Note that this plugin aims to provide abstractions for all platforms as opposed to having methods that only work on specific platforms. However, each method allows passing in "platform-specifics" that contains data that is specific for customising notifications on each platform. This approach means that some scenarios may not be covered by the plugin. Developers can either fork or maintain their code for showing notifications in these situations. Note that the plugin still under development so expect the API surface to change over time.
@@ -79,7 +79,7 @@ var initializationSettingsIOS = IOSInitializationSettings(
     onDidReceiveLocalNotification: onDidReceiveLocalNotification);
 var initializationSettings = InitializationSettings(
     initializationSettingsAndroid, initializationSettingsIOS);
-flutterLocalNotificationsPlugin.initialize(initializationSettings,
+await flutterLocalNotificationsPlugin.initialize(initializationSettings,
     onSelectNotification: onSelectNotification);
 ```
 
@@ -101,15 +101,15 @@ In the real world, this payload could represent the id of the item you want to d
 
 *Notes around initialisation*: if the app had been launched by tapping on a notification created by this plugin, calling `initialize` is what will trigger the `onSelectNotification` to trigger to handle the notification that the user tapped on. An alternative to handling the "launch notification" is to call the `getNotificationAppLaunchDetails` method that is available in the plugin. This could be used, for example, to change the home route of the app for deep-linking. Calling `initialize` will still cause the `onSelectNotification` callback to fire for the launch notification. It will be up to developers to ensure that they don't process the same notification twice (e.g. by storing and comparing the notification id).
 
-### [iOS only] Requesting notification permission
+### [iOS only] Requesting notification permissions
 
-By default this plugin will request notification permission when it is initialized. `IOSInitializationSettings` have three named parameters:
+By default this plugin will request notification permissions when it is initialised. `IOSInitializationSettings` have three named parameters:
 1. `requestSoundPermission`,
 1. `requestBadgePermission`,
 1. `requestAlertPermission`
 that control this behaviour.
 
-If you want to delay permission request, set all of the above to false.
+If you want to request permissions at a later point in your application, set all of the above to false.
 
 ```dart
 FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin = new FlutterLocalNotificationsPlugin();
@@ -123,11 +123,11 @@ var initializationSettingsIOS = new IOSInitializationSettings(
     );
 var initializationSettings = new InitializationSettings(
     initializationSettingsAndroid, initializationSettingsIOS);
-flutterLocalNotificationsPlugin.initialize(initializationSettings,
+await flutterLocalNotificationsPlugin.initialize(initializationSettings,
     onSelectNotification: onSelectNotification);
 ```
 
-Then later call `requestPermissions` method with desired permissions.
+Then call `requestPermissions` method with desired permissions at the appropriate point in your application
 
 ```dart
 var result = await IOSFlutterLocalNotificationsPlugin.instance?.requestPermissions(
@@ -306,7 +306,7 @@ await flutterLocalNotificationsPlugin.cancelAll();
 ```
 
 
-### Get details on if the app was launched via a notification
+### Get details on if the app was launched via a notification created by this plugin
 
 ```dart
  var notificationAppLaunchDetails =

flutter_local_notifications/example/lib/main.dart

@@ -45,6 +45,8 @@ Future<void> main() async {
   //     await flutterLocalNotificationsPlugin.getNotificationAppLaunchDetails();
 
   var initializationSettingsAndroid = AndroidInitializationSettings('app_icon');
+  // Note: permissions aren't requested here just to demonstrate that can be done later using the `requestPermissions()` method
+  // of the `IOSFlutterLocalNotificationsPlugin` class
   var initializationSettingsIOS = IOSInitializationSettings(
       requestAlertPermission: false,
       requestBadgePermission: false,
@@ -56,13 +58,14 @@ Future<void> main() async {
       });
   var initializationSettings = InitializationSettings(
       initializationSettingsAndroid, initializationSettingsIOS);
-  await flutterLocalNotificationsPlugin.initialize(initializationSettings,
-      onSelectNotification: (String payload) async {
+  var initialised = await flutterLocalNotificationsPlugin.initialize(
+      initializationSettings, onSelectNotification: (String payload) async {
     if (payload != null) {
       debugPrint('notification payload: ' + payload);
     }
     selectNotificationSubject.add(payload);
   });
+  print('initialised: $initialised');
   runApp(
     MaterialApp(
       home: HomePage(),

flutter_local_notifications/lib/src/flutter_local_notifications_plugin.dart

@@ -11,13 +11,15 @@ import 'platform_flutter_local_notifications.dart';
 import 'typedefs.dart';
 import 'types.dart';
 
-/// `FlutterLocalNotificationsPlugin` allows applications to display a local notification.
+/// Provides cross-platform functionality for displaying local notifications.
+///
 /// The plugin will check the platform that is running on to use the appropriate platform-specific
 /// implementation of the plugin. The plugin methods will be a no-op when the platform can't be detected.
 class FlutterLocalNotificationsPlugin {
   factory FlutterLocalNotificationsPlugin() => _instance;
 
   /// Used internally for creating the appropriate platform-specific implementation of the plugin.
+  ///
   /// This can be used for tests as well. For example, the following code
   ///
   /// ```
@@ -42,12 +44,21 @@ class FlutterLocalNotificationsPlugin {
 
   final Platform _platform;
 
-  /// Initializes the plugin. Call this method on application before using the plugin further.
-  /// This should only be done once. When a notification created by this plugin was used to launch the app,
-  /// calling `initialize` is what will trigger to the `onSelectNotification` callback to be fire.
+  /// Initializes the plugin.
+  ///
+  /// Call this method on application before using the plugin further. This should only be done once. When a notification
+  /// created by this plugin was used to launch the app, calling `initialize` is what will trigger to the `onSelectNotification`
+  /// callback to be fire.
+  ///
+  /// Will return a [bool] value to indicate if initialization succeeded. On iOS this is dependent on if permissions have been
+  /// granted to show notification When running in environment that is neither Android and iOS (e.g. when running tests),
+  /// this will be a no-op and return true.
   ///
-  /// Will return a [bool] value to indicate if initialization succeeded. When running in environment that is
-  /// neither Android and iOS (e.g. when running tests), this will be a no-op and return true.
+  /// Note that on iOS, initialisation may also request notification permissions where users will see a permissions prompt.
+  /// This may be fine in cases where it's acceptable to do this when the application runs for the first time. However, if your application
+  /// needs to do this at a later point in time, set the [IOSInitializationSettings.requestAlertPermission],
+  /// [IOSInitializationSettings.requestBadgePermission] and [IOSInitializationSettings.requestSoundPermission] values to false.
+  /// [requestPermissions] can then be called to request permissions when needed.
   Future<bool> initialize(InitializationSettings initializationSettings,
       {SelectNotificationCallback onSelectNotification}) async {
     if (_platform.isAndroid) {
@@ -64,9 +75,9 @@ class FlutterLocalNotificationsPlugin {
     return true;
   }
 
-  /// Returns info on if a notification had been used to launch the application.
-  /// An example of how this could be used is to change the initial route of your application when it starts up.
+  /// Returns info on if a notification created from this plugin had been used to launch the application.
   ///
+  /// An example of how this could be used is to change the initial route of your application when it starts up.
   /// If the plugin isn't running on either Android or iOS then it defaults to indicate that a notification wasn't
   /// used to launch the app.
   Future<NotificationAppLaunchDetails> getNotificationAppLaunchDetails() async {
@@ -85,7 +96,7 @@ class FlutterLocalNotificationsPlugin {
     }
   }
 
-  /// Show a notification with an optional payload that will be passed back to the app when a notification is tapped
+  /// Show a notification with an optional payload that will be passed back to the app when a notification is tapped.
   Future<void> show(int id, String title, String body,
       NotificationDetails notificationDetails,
       {String payload}) async {
@@ -105,17 +116,22 @@ class FlutterLocalNotificationsPlugin {
     }
   }
 
-  /// Cancel/remove the notification with the specified id. This applies to notifications that have been scheduled and those that have already been presented.
+  /// Cancel/remove the notification with the specified id.
+  ///
+  /// This applies to notifications that have been scheduled and those that have already been presented.
   Future<void> cancel(int id) async {
     await FlutterLocalNotificationsPlatform.instance?.cancel(id);
   }
 
-  /// Cancels/removes all notifications. This applies to notifications that have been scheduled and those that have already been presented.
+  /// Cancels/removes all notifications.
+  ///
+  /// This applies to notifications that have been scheduled and those that have already been presented.
   Future<void> cancelAll() async {
     await FlutterLocalNotificationsPlatform.instance?.cancelAll();
   }
 
-  /// Schedules a notification to be shown at the specified time with an optional payload that is passed through when a notification is tapped
+  /// Schedules a notification to be shown at the specified time with an optional payload that is passed through when a notification is tapped.
+  ///
   /// The [androidAllowWhileIdle] parameter is Android-specific and determines if the notification should still be shown at the specified time
   /// even when in a low-power idle mode.
   Future<void> schedule(int id, String title, String body,
@@ -136,6 +152,7 @@ class FlutterLocalNotificationsPlugin {
   }
 
   /// Periodically show a notification using the specified interval.
+  ///
   /// For example, specifying a hourly interval means the first time the notification will be an hour after the method has been called and then every hour after that.
   Future<void> periodicallyShow(int id, String title, String body,
       RepeatInterval repeatInterval, NotificationDetails notificationDetails,
@@ -157,7 +174,7 @@ class FlutterLocalNotificationsPlugin {
     }
   }
 
-  /// Shows a notification on a daily interval at the specified time
+  /// Shows a notification on a daily interval at the specified time.
   Future<void> showDailyAtTime(int id, String title, String body,
       Time notificationTime, NotificationDetails notificationDetails,
       {String payload}) async {
@@ -176,7 +193,7 @@ class FlutterLocalNotificationsPlugin {
     }
   }
 
-  /// Shows a notification on a daily interval at the specified time
+  /// Shows a notification on a daily interval at the specified time.
   Future<void> showWeeklyAtDayAndTime(int id, String title, String body,
       Day day, Time notificationTime, NotificationDetails notificationDetails,
       {String payload}) async {
@@ -195,7 +212,7 @@ class FlutterLocalNotificationsPlugin {
     }
   }
 
-  /// Returns a list of notifications pending to be delivered/shown
+  /// Returns a list of notifications pending to be delivered/shown.
   Future<List<PendingNotificationRequest>> pendingNotificationRequests() {
     return FlutterLocalNotificationsPlatform.instance
         ?.pendingNotificationRequests();

flutter_local_notifications/lib/src/platform_flutter_local_notifications.dart

@@ -198,6 +198,12 @@ class IOSFlutterLocalNotificationsPlugin
   /// Initializes the plugin. Call this method on application before using the plugin further.
   /// This should only be done once. When a notification created by this plugin was used to launch the app,
   /// calling `initialize` is what will trigger to the `onSelectNotification` callback to be fire.
+  ///
+  /// Initialisation may also request notification permissions where users will see a permissions prompt. This may be fine
+  /// in cases where it's acceptable to do this when the application runs for the first time. However, if your application
+  /// needs to do this at a later point in time, set the [IOSInitializationSettings.requestAlertPermission],
+  /// [IOSInitializationSettings.requestBadgePermission] and [IOSInitializationSettings.requestSoundPermission] values to false.
+  /// [requestPermissions] can then be called to request permissions when needed.
   Future<bool> initialize(IOSInitializationSettings initializationSettings,
       {SelectNotificationCallback onSelectNotification}) async {
     _onSelectNotification = onSelectNotification;

flutter_local_notifications/lib/src/platform_specifics/android/enums.dart

@@ -1,10 +1,10 @@
 /// Specifies the source for a bitmap used by Android notifications.
 enum BitmapSource { Drawable, FilePath }
 
-/// Specifies the source for icons
+/// Specifies the source for icons.
 enum IconSource { Drawable, FilePath, ContentUri }
 
-/// The available notification styles on Android
+/// The available notification styles on Android.
 enum AndroidNotificationStyle {
   Default,
   BigPicture,
@@ -15,11 +15,13 @@ enum AndroidNotificationStyle {
 }
 
 /// The available actions for managing notification channels.
-/// [CreateIfNotExists]: will create a channel if it doesn't exist
-/// [Update]: will update the details of an existing channel. Note that some details can not be changed once a channel has been created
+///
+/// [CreateIfNotExists]: will create a channel if it doesn't exist.
+/// [Update]: will update the details of an existing channel. Note that some details can not be changed once a channel has been created.
 enum AndroidNotificationChannelAction { CreateIfNotExists, Update }
 
 /// The available importance levels for Android notifications.
+///
 /// Required for Android 8.0+
 class Importance {
   static const Unspecified = Importance(-1000);
@@ -37,7 +39,7 @@ class Importance {
   const Importance(this.value);
 }
 
-/// Priority for notifications on Android 7.1 and lower
+/// Priority for notifications on Android 7.1 and lower.
 class Priority {
   static const Min = Priority(-2);
   static const Low = Priority(-1);
@@ -52,10 +54,10 @@ class Priority {
   const Priority(this.value);
 }
 
-/// The available alert behaviours for grouped notifications
+/// The available alert behaviours for grouped notifications.
 enum GroupAlertBehavior { All, Summary, Children }
 
-/// Defines the notification visibility on the lockscreen
+/// Defines the notification visibility on the lockscreen.
 enum NotificationVisibility {
   /// Show this notification on all lockscreens, but conceal sensitive or private information on secure lockscreens.
   Private,

flutter_local_notifications/lib/src/platform_specifics/android/initialization_settings.dart

@@ -1,6 +1,6 @@
-/// Plugin initialization settings for Android
+/// Plugin initialization settings for Android.
 class AndroidInitializationSettings {
-  /// Sets the default icon for notifications
+  /// Sets the default icon for notifications.
   final String defaultIcon;
 
   const AndroidInitializationSettings(this.defaultIcon);

flutter_local_notifications/lib/src/platform_specifics/android/message.dart

@@ -1,20 +1,24 @@
 import 'person.dart';
 
-/// Represents a message used in Android messaging style notifications
+/// Represents a message used in Android messaging style notifications.
 class Message {
   /// The message text
   final String text;
 
-  /// Time at which the message arrived. Note that this is eventually converted to milliseconds since epoch as required by Android
+  /// Time at which the message arrived.
+  ///
+  /// Note that this is eventually converted to milliseconds since epoch as required by Android.
   final DateTime timestamp;
 
-  /// Person that sent this message
+  /// Person that sent this message.
   final Person person;
 
-  /// MIME type for this message context when the [dataUri] is provided
+  /// MIME type for this message context when the [dataUri] is provided.
   final String dataMimeType;
 
-  /// Uri containing the content. The original text will be used if the content or MIME type isn't supported
+  /// Uri containing the content.
+  ///
+  /// The original text will be used if the content or MIME type isn't supported
   final String dataUri;
 
   Message(this.text, this.timestamp, this.person,