Clean up JavaDoc for GeolocationPermissions

Much of the current JavaDoc for GeolocationPermissions exposes implementation
details which are of no interest to a Java developer. Move these comments out
of the JavaDoc and clean up the text.

Bug: 5461416
Change-Id: I95a68fe15016fadc729d8d857fd69b2c927a5ea9

3 files changed, 81 insertions, 41 deletions

diff --git a/core/java/android/webkit/GeolocationPermissions.java b/core/java/android/webkit/GeolocationPermissions.java
index 5d54180..d7b6adb 100755
--- a/core/java/android/webkit/GeolocationPermissions.java
+++ b/core/java/android/webkit/GeolocationPermissions.java
@@ -27,30 +27,47 @@ import java.util.Vector;
 
 
 /**
- * This class is used to get Geolocation permissions from, and set them on the
- * WebView. For example, it could be used to allow a user to manage Geolocation
- * permissions from a browser's UI.
+ * This class is used to manage permissions for the WebView's Geolocation
+ * JavaScript API.
  *
- * Permissions are managed on a per-origin basis, as required by the
- * Geolocation spec - http://dev.w3.org/geo/api/spec-source.html. An origin
- * specifies the scheme, host and port of particular frame. An origin is
- * represented here as a string, using the output of
- * WebCore::SecurityOrigin::toString.
+ * Geolocation permissions are applied to an origin, which consists of the
+ * host, scheme and port of a URI. In order for web content to use the
+ * Geolocation API, permission must be granted for that content's origin.
  *
- * This class is the Java counterpart of the WebKit C++ GeolocationPermissions
- * class. It simply marshalls calls from the UI thread to the WebKit thread.
+ * This class stores Geolocation permissions. An origin's permission state can
+ * be either allowed or denied. This class uses Strings to represent
+ * an origin.
  *
- * Within WebKit, Geolocation permissions may be applied either temporarily
- * (for the duration of the page) or permanently. This class deals only with
- * permanent permissions.
+ * When an origin attempts to use the Geolocation API, but no permission state
+ * is currently set for that origin,
+ * {@link WebChromeClient#onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) WebChromeClient.onGeolocationPermissionsShowPrompt()}
+ * is called. This allows the permission state to be set for that origin.
+ *
+ * The methods of this class can be used to modify and interrogate the stored
+ * Geolocation permissions at any time.
  */
+// This class is the Java counterpart of the WebKit C++ GeolocationPermissions
+// class. It simply marshalls calls from the UI thread to the WebKit thread.
+//
+// Within WebKit, Geolocation permissions may be applied either temporarily
+// (for the duration of the page) or permanently. This class deals only with
+// permanent permissions.
 public final class GeolocationPermissions {
     /**
-     * Callback interface used by the browser to report a Geolocation permission
-     * state set by the user in response to a permissions prompt.
+     * A callback interface used by the host application to set the Geolocation
+     * permission state for an origin.
      */
     public interface Callback {
-        public void invoke(String origin, boolean allow, boolean remember);
+        /**
+         * Set the Geolocation permission state for the supplied origin.
+         * @param origin The origin for which permissions are set.
+         * @param allow Whether or not the origin should be allowed to use the
+         *              Geolocation API.
+         * @param retain Whether the permission should be retained beyond the
+         *               lifetime of a page currently being displayed by a
+         *               WebView.
+         */
+        public void invoke(String origin, boolean allow, boolean retain);
     };
 
     // Log tag
@@ -82,7 +99,8 @@ public final class GeolocationPermissions {
     private static final String ALLOWED = "allowed";
 
     /**
-     * Gets the singleton instance of the class.
+     * Get the singleton instance of this class.
+     * @return The singleton {@link GeolocationPermissions} instance.
      */
     public static GeolocationPermissions getInstance() {
       if (sInstance == null) {
@@ -196,15 +214,18 @@ public final class GeolocationPermissions {
     }
 
     /**
-     * Gets the set of origins for which Geolocation permissions are stored.
-     * Note that we represent the origins as strings. These are created using
-     * WebCore::SecurityOrigin::toString(). As long as all 'HTML 5 modules'
-     * (Database, Geolocation etc) do so, it's safe to match up origins based
-     * on this string.
-     *
-     * Callback is a ValueCallback object whose onReceiveValue method will be
-     * called asynchronously with the set of origins.
+     * Get the set of origins for which Geolocation permissions are stored.
+     * @param callback A {@link ValueCallback} to receive the result of this
+     *                 request. This object's
+     *                 {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
+     *                 method will be invoked asynchronously with a set of
+     *                 Strings containing the origins for which Geolocation
+     *                 permissions are stored.
      */
+    // Note that we represent the origins as strings. These are created using
+    // WebCore::SecurityOrigin::toString(). As long as all 'HTML 5 modules'
+    // (Database, Geolocation etc) do so, it's safe to match up origins based
+    // on this string.
     public void getOrigins(ValueCallback<Set<String> > callback) {
         if (callback != null) {
             if (WebViewCore.THREAD_NAME.equals(Thread.currentThread().getName())) {
@@ -217,10 +238,14 @@ public final class GeolocationPermissions {
     }
 
     /**
-     * Gets the permission state for the specified origin.
-     *
-     * Callback is a ValueCallback object whose onReceiveValue method will be
-     * called asynchronously with the permission state for the origin.
+     * Get the Geolocation permission state for the specified origin.
+     * @param origin The origin for which Geolocation permission is requested.
+     * @param callback A {@link ValueCallback} to receive the result of this
+     *                 request. This object's
+     *                 {@link ValueCallback#onReceiveValue(T) onReceiveValue()}
+     *                 method will be invoked asynchronously with a boolean
+     *                 indicating whether or not the origin can use the
+     *                 Geolocation API.
      */
     public void getAllowed(String origin, ValueCallback<Boolean> callback) {
         if (callback == null) {
@@ -242,27 +267,31 @@ public final class GeolocationPermissions {
     }
 
     /**
-     * Clears the permission state for the specified origin. This method may be
-     * called before the WebKit thread has intialized the message handler.
-     * Messages will be queued until this time.
+     * Clear the Geolocation permission state for the specified origin.
+     * @param origin The origin for which Geolocation permissions are cleared.
      */
+    // This method may be called before the WebKit
+    // thread has intialized the message handler. Messages will be queued until
+    // this time.
     public void clear(String origin) {
         // Called on the UI thread.
         postMessage(Message.obtain(null, CLEAR, origin));
     }
 
     /**
-     * Allows the specified origin. This method may be called before the WebKit
-     * thread has intialized the message handler. Messages will be queued until
-     * this time.
+     * Allow the specified origin to use the Geolocation API.
+     * @param origin The origin for which Geolocation API use is allowed.
      */
+    // This method may be called before the WebKit
+    // thread has intialized the message handler. Messages will be queued until
+    // this time.
     public void allow(String origin) {
         // Called on the UI thread.
         postMessage(Message.obtain(null, ALLOW, origin));
     }
 
     /**
-     * Clears the permission state for all origins.
+     * Clear the Geolocation permission state for all origins.
      */
     public void clearAll() {
         // Called on the UI thread.
diff --git a/core/java/android/webkit/ValueCallback.java b/core/java/android/webkit/ValueCallback.java
index 1a167e8..5c7d97f 100644
--- a/core/java/android/webkit/ValueCallback.java
+++ b/core/java/android/webkit/ValueCallback.java
@@ -17,11 +17,12 @@
 package android.webkit;
 
 /**
- * A callback interface used to returns values asynchronously
+ * A callback interface used to provide values asynchronously.
  */
 public interface ValueCallback<T> {
     /**
-     * Invoked when we have the result
+     * Invoked when the value is available.
+     * @param value The value.
      */
     public void onReceiveValue(T value);
 };
diff --git a/core/java/android/webkit/WebChromeClient.java b/core/java/android/webkit/WebChromeClient.java
index 3d129f7..a6ef0ce 100644
--- a/core/java/android/webkit/WebChromeClient.java
+++ b/core/java/android/webkit/WebChromeClient.java
@@ -250,14 +250,24 @@ public class WebChromeClient {
     }
 
     /**
-     * Instructs the client to show a prompt to ask the user to set the
-     * Geolocation permission state for the specified origin.
+     * Notify the host application that web content from the specified origin
+     * is attempting to use the Geolocation API, but no permission state is
+     * currently set for that origin. The host application should invoke the
+     * specified callback with the desired permission state. See
+     * {@link GeolocationPermissions} for details.
+     * @param origin The origin of the web content attempting to use the
+     *               Geolocation API.
+     * @param callback The callback to use to set the permission state for the
+     *                 origin.
      */
     public void onGeolocationPermissionsShowPrompt(String origin,
             GeolocationPermissions.Callback callback) {}
 
     /**
-     * Instructs the client to hide the Geolocation permissions prompt.
+     * Notify the host application that a request for Geolocation permissions,
+     * made with a previous call to
+     * {@link #onGeolocationPermissionsShowPrompt(String,GeolocationPermissions.Callback) onGeolocationPermissionsShowPrompt()}
+     * has been canceled. Any related UI should therefore be hidden.
      */
     public void onGeolocationPermissionsHidePrompt() {}