Add documentation to the NotificationPermissionContext

Change-Id: I1ec42b183f800555145b4a78db898d61efaab456
Reviewed-on: https://chromium-review.googlesource.com/1113183
Commit-Queue: Peter Beverloo <peter@chromium.org>
Reviewed-by: Dan Elphick <delphick@chromium.org>
Cr-Commit-Position: refs/heads/master@{#570000}

chrome/browser/notifications/notification_permission_context.h

@@ -13,6 +13,71 @@
 class GURL;
 class Profile;
 
+// This permission context is responsible for getting, deciding on and updating
+// the notification permission for a particular website or extension. This
+// permission guards use of the Notification API, the Web Push API and the
+// chrome.notifications extension APIs.
+//
+// https://notifications.spec.whatwg.org/
+// https://w3c.github.io/push-api/
+// https://developer.chrome.com/apps/notifications
+//
+// -----------------------------------------------------------------------------
+// Websites
+// -----------------------------------------------------------------------------
+//
+// Websites running top-level on a secure origin are able to request the
+// notification permission by calling Notification.requestPermission(), or
+// implicitly through PushManager.subscribe(). Requests from insecure origins
+// and sub-frames are rejected, but can use previously granted permission.
+//
+// When a website running in a sub-frame checks whether permission has been
+// granted, and no decision has been made yet (i.e. CONTENT_SETTING_ASK),
+// CONTENT_SETTING_BLOCK will be returned to reflect the fact that permission
+// cannot be requested.
+//
+// ANDROID O+
+//
+//     On Android O and beyond, notification channels will be used for storing
+//     website permissions as opposed to regular preferences. The permissions
+//     are configurable by the user in system UI, and will be backed up and
+//     restored by the operating system at the appropriate times.
+//
+//         Settings > Apps & notifications > Chrome > Notifications > Sites
+//
+//     The NotificationChannelsProviderAndroid implements this behaviour, and
+//     is added as a content setting provider to the HostContentSettingsMap.
+//
+// https://developer.android.com/guide/topics/ui/notifiers/notifications#ManageChannels
+//
+// INCOGNITO
+//
+//    The notification permission is not available in Incognito browsing mode
+//    because the expected behaviour regarding short-lived push subscriptions
+//    has not been decided upon. Use of native notification centers, where
+//    Chrome hands over potentially sensitive information to the underlying
+//    operating system, will also be a consideration in this decision.
+//
+//    An explicit design goal of Incognito mode is that developers should not be
+//    able to recognise that it is being used. Applicable permission requests
+//    are therefore automatically rejected after a random number of seconds in
+//    the range [1.0, 2.0).
+//
+// -----------------------------------------------------------------------------
+// Extensions
+// -----------------------------------------------------------------------------
+//
+// Extensions that wish to use notifications should declare the "notifications"
+// permission in their manifest. The user will be prompted to accept this when
+// the extension is being installed, or installation will be aborted.
+//
+// An installed extension that declared the "notifications" permission in their
+// manifest is assumed to have full permission. This can be overridden by the
+// NotifierStateTracker, configurable through UI affordances such as the Chrome
+// OS Notification Center and the right click -> "disable notifications" option.
+//
+// Extensions that do not declare the "notifications" permission in their
+// manifest will be treated as regular websites.
 class NotificationPermissionContext : public PermissionContextBase {
  public:
   // Helper method for updating the permission state of |origin| to |setting|.