Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 4e584df4 authored by Steve Block's avatar Steve Block
Browse files

Fix JavaDoc style for several WebView classes 

This fixes the JavaDoc style for the following classes ...
- CacheManager.java
- CookieManager.java
- GeolocationPermissions.java
- WebResourceResponse.java
- WebSettings.java
- WebStorage.java
- WebView.java

In particular, this applies the guidelines at
https://wiki.corp.google.com/twiki/bin/view/Main/APIDocumentation

This should help to ensure that future JavaDoc comments use correct style,
rather than using incorrect style for consistency.

Note that this change does not attempt to improve the content of the JavaDoc
comments. This will be done in later changes.

Bug: 5461416
Change-Id: I79e9b15a8cf3597195d58e154a7eb1bcc462944c
parent e9e260fb

core/java/android/webkit/CacheManager.java

+55 −31
Original line number Diff line number Diff line
@@ -56,6 +56,7 @@ public final class CacheManager { 
     * Represents a resource stored in the HTTP cache. Instances of this class

     * can be obtained by calling

     * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>))}.

     *

     * @deprecated Access to the HTTP cache will be removed in a future release.

     */

    @Deprecated
@@ -81,7 +82,8 @@ public final class CacheManager { 


        /**

         * Gets the status code of this cache entry.

         * @return The status code of this cache entry

         *

         * @return the status code of this cache entry

         */

        public int getHttpStatusCode() {

            return httpStatusCode;
@@ -89,7 +91,8 @@ public final class CacheManager { 


        /**

         * Gets the content length of this cache entry.

         * @return The content length of this cache entry

         *

         * @return the content length of this cache entry

         */

        public long getContentLength() {

            return contentLength;
@@ -99,7 +102,8 @@ public final class CacheManager { 
         * Gets the path of the file used to store the content of this cache

         * entry, relative to the base directory of the cache. See

         * {@link CacheManager#getCacheFileBaseDir CacheManager.getCacheFileBaseDir()}.

         * @return The path of the file used to store this cache entry

         *

         * @return the path of the file used to store this cache entry

         */

        public String getLocalPath() {

            return localPath;
@@ -108,7 +112,8 @@ public final class CacheManager { 
        /**

         * Gets the expiry date of this cache entry, expressed in milliseconds

         * since midnight, January 1, 1970 UTC.

         * @return The expiry date of this cache entry

         *

         * @return the expiry date of this cache entry

         */

        public long getExpires() {

            return expires;
@@ -116,7 +121,8 @@ public final class CacheManager { 


        /**

         * Gets the expiry date of this cache entry, expressed as a string.

         * @return The expiry date of this cache entry

         *

         * @return the expiry date of this cache entry

         *

         */

        public String getExpiresString() {
@@ -126,7 +132,8 @@ public final class CacheManager { 
        /**

         * Gets the date at which this cache entry was last modified, expressed

         * as a string.

         * @return The date at which this cache entry was last modified

         *

         * @return the date at which this cache entry was last modified

         */

        public String getLastModified() {

            return lastModified;
@@ -134,7 +141,8 @@ public final class CacheManager { 


        /**

         * Gets the entity tag of this cache entry.

         * @return The entity tag of this cache entry

         *

         * @return the entity tag of this cache entry

         */

        public String getETag() {

            return etag;
@@ -142,7 +150,8 @@ public final class CacheManager { 


        /**

         * Gets the MIME type of this cache entry.

         * @return The MIME type of this cache entry

         *

         * @return the MIME type of this cache entry

         */

        public String getMimeType() {

            return mimeType;
@@ -151,7 +160,8 @@ public final class CacheManager { 
        /**

         * Gets the value of the HTTP 'Location' header with which this cache

         * entry was received.

         * @return The HTTP 'Location' header for this cache entry

         *

         * @return the HTTP 'Location' header for this cache entry

         */

        public String getLocation() {

            return location;
@@ -159,7 +169,8 @@ public final class CacheManager { 


        /**

         * Gets the encoding of this cache entry.

         * @return The encoding of this cache entry

         *

         * @return the encoding of this cache entry

         */

        public String getEncoding() {

            return encoding;
@@ -168,7 +179,8 @@ public final class CacheManager { 
        /**

         * Gets the value of the HTTP 'Content-Disposition' header with which

         * this cache entry was received.

         * @return The HTTP 'Content-Disposition' header for this cache entry

         *

         * @return the HTTP 'Content-Disposition' header for this cache entry

         *

         */

        public String getContentDisposition() {
@@ -179,7 +191,8 @@ public final class CacheManager { 
         * Gets the input stream to the content of this cache entry, to allow

         * content to be read. See

         * {@link CacheManager#getCacheFile CacheManager.getCacheFile(String, Map<String, String>)}.

         * @return An input stream to the content of this cache entry

         *

         * @return an input stream to the content of this cache entry

         */

        public InputStream getInputStream() {

            return inStream;
@@ -189,7 +202,8 @@ public final class CacheManager { 
         * Gets an output stream to the content of this cache entry, to allow

         * content to be written. See

         * {@link CacheManager#saveCacheFile CacheManager.saveCacheFile(String, CacheResult)}.

         * @return An output stream to the content of this cache entry

         *

         * @return an output stream to the content of this cache entry

         */

        // Note that this is always null for objects returned by getCacheFile()!

        public OutputStream getOutputStream() {
@@ -199,7 +213,8 @@ public final class CacheManager { 


        /**

         * Sets an input stream to the content of this cache entry.

         * @param stream An input stream to the content of this cache entry

         *

         * @param stream an input stream to the content of this cache entry

         */

        public void setInputStream(InputStream stream) {

            this.inStream = stream;
@@ -207,7 +222,8 @@ public final class CacheManager { 


        /**

         * Sets the encoding of this cache entry.

         * @param encoding The encoding of this cache entry

         *

         * @param encoding the encoding of this cache entry

         */

        public void setEncoding(String encoding) {

            this.encoding = encoding;
@@ -225,7 +241,8 @@ public final class CacheManager { 
     * Initializes the HTTP cache. This method must be called before any

     * CacheManager methods are used. Note that this is called automatically

     * when a {@link WebView} is created.

     * @param context The application context

     *

     * @param context the application context

     */

    static void init(Context context) {

        // This isn't actually where the real cache lives, but where we put files for the
@@ -240,7 +257,8 @@ public final class CacheManager { 
     * Gets the base directory in which the files used to store the contents of

     * cache entries are placed. See

     * {@link CacheManager.CacheResult#getLocalPath CacheManager.CacheResult.getLocalPath()}.

     * @return The base directory of the cache

     *

     * @return the base directory of the cache

     * @deprecated Access to the HTTP cache will be removed in a future release.

     */

    @Deprecated
@@ -250,7 +268,8 @@ public final class CacheManager { 


    /**

     * Gets whether the HTTP cache is disabled.

     * @return True if the HTTP cache is disabled

     *

     * @return true if the HTTP cache is disabled

     * @deprecated Access to the HTTP cache will be removed in a future release.

     */

    @Deprecated
@@ -262,8 +281,9 @@ public final class CacheManager { 
     * Starts a cache transaction. Returns true if this is the only running

     * transaction. Otherwise, this transaction is nested inside currently

     * running transactions and false is returned.

     * @return True if this is the only running transaction

     * @deprecated This method no longer has any effect and always returns false

     *

     * @return true if this is the only running transaction

     * @deprecated This method no longer has any effect and always returns false.

     */

    @Deprecated

    public static boolean startCacheTransaction() {
@@ -273,8 +293,9 @@ public final class CacheManager { 
    /**

     * Ends the innermost cache transaction and returns whether this was the

     * only running transaction.

     * @return True if this was the only running transaction

     * @deprecated This method no longer has any effect and always returns false

     *

     * @return true if this was the only running transaction

     * @deprecated This method no longer has any effect and always returns false.

     */

    @Deprecated

    public static boolean endCacheTransaction() {
@@ -287,10 +308,11 @@ public final class CacheManager { 
     * entry needs validation, appropriate headers will be added to the map.

     * The input stream of the CacheEntry object should be closed by the caller

     * when access to the underlying file is no longer required.

     * @param url The URL for which a cache entry is requested

     * @param headers A map from HTTP header name to value, to be populated

     *

     * @param url the URL for which a cache entry is requested

     * @param headers a map from HTTP header name to value, to be populated

     *                for the returned cache entry

     * @return The cache entry for the specified URL

     * @return the cache entry for the specified URL

     * @deprecated Access to the HTTP cache will be removed in a future release.

     */

    @Deprecated
@@ -345,14 +367,15 @@ public final class CacheManager { 
    }



    /**

     * Given a url and its full headers, returns CacheResult if a local cache

     * Given a URL and its full headers, gets a CacheResult if a local cache

     * can be stored. Otherwise returns null. The mimetype is passed in so that

     * the function can use the mimetype that will be passed to WebCore which

     * could be different from the mimetype defined in the headers.

     * forceCache is for out-of-package callers to force creation of a

     * CacheResult, and is used to supply surrogate responses for URL

     * interception.

     * @return CacheResult for a given url

     *

     * @return a CacheResult for a given URL

     */

    static CacheResult createCacheFile(String url, int statusCode,

            Headers headers, String mimeType, boolean forceCache) {
@@ -363,8 +386,9 @@ public final class CacheManager { 
    /**

     * Adds a cache entry to the HTTP cache for the specicifed URL. Also closes

     * the cache entry's output stream.

     * @param url The URL for which the cache entry should be added

     * @param cacheResult The cache entry to add

     *

     * @param url the URL for which the cache entry should be added

     * @param cacheResult the cache entry to add

     * @deprecated Access to the HTTP cache will be removed in a future release.

     */

    @Deprecated
@@ -401,9 +425,9 @@ public final class CacheManager { 
    }



    /**

     * Remove all cache files.

     * Removes all cache files.

     *

     * @return Whether the removal succeeded.

     * @return whether the removal succeeded

     */

    static boolean removeAllCacheFiles() {

        // delete cache files in a separate thread to not block UI.

core/java/android/webkit/CookieManager.java

+31 −20
Original line number Diff line number Diff line
@@ -40,7 +40,7 @@ public class CookieManager { 
     * {@link CookieSyncManager#createInstance(Context)} must be called

     * first.

     *

     * @return The singleton CookieManager instance

     * @return the singleton CookieManager instance

     */

    public static synchronized CookieManager getInstance() {

        return WebViewFactory.getProvider().getCookieManager();
@@ -49,7 +49,8 @@ public class CookieManager { 
    /**

     * Sets whether the application's {@link WebView} instances should send and

     * accept cookies.

     * @param accept Whether {@link WebView} instances should send and accept

     *

     * @param accept whether {@link WebView} instances should send and accept

     *               cookies

     */

    public synchronized void setAcceptCookie(boolean accept) {
@@ -59,7 +60,8 @@ public class CookieManager { 
    /**

     * Gets whether the application's {@link WebView} instances send and accept

     * cookies.

     * @return True if {@link WebView} instances send and accept cookies

     *

     * @return true if {@link WebView} instances send and accept cookies

     */

    public synchronized boolean acceptCookie() {

        throw new MustOverrideException();
@@ -70,8 +72,9 @@ public class CookieManager { 
     * path and name will be replaced with the new cookie. The cookie being set

     * must not have expired and must not be a session cookie, otherwise it

     * will be ignored.

     * @param url The URL for which the cookie is set

     * @param value The cookie as a string, using the format of the 'Set-Cookie'

     *

     * @param url the URL for which the cookie is set

     * @param value the cookie as a string, using the format of the 'Set-Cookie'

     *              HTTP response header

     */

    public void setCookie(String url, String value) {
@@ -80,8 +83,9 @@ public class CookieManager { 


    /**

     * Gets the cookies for the given URL.

     * @param url The URL for which the cookies are requested

     * @return value The cookies as a string, using the format of the 'Cookie'

     *

     * @param url the URL for which the cookies are requested

     * @return value the cookies as a string, using the format of the 'Cookie'

     *               HTTP request header

     */

    public String getCookie(String url) {
@@ -89,10 +93,11 @@ public class CookieManager { 
    }



    /**

     * See {@link #getCookie(String)}

     * @param url The URL for which the cookies are requested

     * @param privateBrowsing Whether to use the private browsing cookie jar

     * @return value The cookies as a string, using the format of the 'Cookie'

     * See {@link #getCookie(String)}.

     *

     * @param url the URL for which the cookies are requested

     * @param privateBrowsing whether to use the private browsing cookie jar

     * @return value the cookies as a string, using the format of the 'Cookie'

     *               HTTP request header

     * @hide Used by Browser, no intention to publish.

     */
@@ -101,10 +106,11 @@ public class CookieManager { 
    }



    /**

     * Get cookie(s) for a given uri so that it can be set to "cookie:" in http

     * Gets cookie(s) for a given uri so that it can be set to "cookie:" in http

     * request header.

     * @param uri The WebAddress for which the cookies are requested

     * @return value The cookies as a string, using the format of the 'Cookie'

     *

     * @param uri the WebAddress for which the cookies are requested

     * @return value the cookies as a string, using the format of the 'Cookie'

     *               HTTP request header

     * @hide Used by RequestHandle, no intention to publish.

     */
@@ -129,7 +135,8 @@ public class CookieManager { 


    /**

     * Gets whether there are stored cookies.

     * @return True if there are stored cookies.

     *

     * @return true if there are stored cookies

     */

    public synchronized boolean hasCookies() {

        throw new MustOverrideException();
@@ -137,7 +144,8 @@ public class CookieManager { 


    /**

     * See {@link #hasCookies()}.

     * @param privateBrowsing Whether to use the private browsing cookie jar

     *

     * @param privateBrowsing whether to use the private browsing cookie jar

     * @hide Used by Browser, no intention to publish.

     */

    public synchronized boolean hasCookies(boolean privateBrowsing) {
@@ -152,7 +160,7 @@ public class CookieManager { 
    }



    /**

     * Flush all cookies managed by the Chrome HTTP stack to flash.

     * Flushes all cookies managed by the Chrome HTTP stack to flash.

     *

     * @hide Package level api, called from CookieSyncManager

     */
@@ -163,7 +171,8 @@ public class CookieManager { 
    /**

     * Gets whether the application's {@link WebView} instances send and accept

     * cookies for file scheme URLs.

     * @return True if {@link WebView} instances send and accept cookies for

     *

     * @return true if {@link WebView} instances send and accept cookies for

     *         file scheme URLs

     */

    // Static for backward compatibility.
@@ -172,7 +181,8 @@ public class CookieManager { 
    }



    /**

     * Implements {@link #allowFileSchemeCookies()}

     * Implements {@link #allowFileSchemeCookies()}.

     *

     * @hide Only for use by WebViewProvider implementations

     */

    protected boolean allowFileSchemeCookiesImpl() {
@@ -195,7 +205,8 @@ public class CookieManager { 
    }



    /**

     * Implements {@link #setAcceptFileSchemeCookies(boolean)}

     * Implements {@link #setAcceptFileSchemeCookies(boolean)}.

     *

     * @hide Only for use by WebViewProvider implementations

     */

    protected void setAcceptFileSchemeCookiesImpl(boolean accept) {

core/java/android/webkit/GeolocationPermissions.java

+24 −18
Original line number Diff line number Diff line
@@ -48,28 +48,31 @@ public class GeolocationPermissions { 
     */

    public interface Callback {

        /**

         * 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

         * Sets 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.

         *               WebView

         */

        public void invoke(String origin, boolean allow, boolean retain);

    };



    /**

     * Get the singleton instance of this class.

     * @return The singleton {@link GeolocationPermissions} instance.

     * Gets the singleton instance of this class.

     *

     * @return the singleton {@link GeolocationPermissions} instance

     */

    public static GeolocationPermissions getInstance() {

      return WebViewFactory.getProvider().getGeolocationPermissions();

    }



    /**

     * Get the set of origins for which Geolocation permissions are stored.

     * @param callback A {@link ValueCallback} to receive the result of this

     * Gets 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
@@ -85,9 +88,10 @@ public class GeolocationPermissions { 
    }



    /**

     * 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

     * Gets 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
@@ -99,23 +103,25 @@ public class GeolocationPermissions { 
    }



    /**

     * Clear the Geolocation permission state for the specified origin.

     * @param origin The origin for which Geolocation permissions are cleared.

     * Clears the Geolocation permission state for the specified origin.

     *

     * @param origin the origin for which Geolocation permissions are cleared

     */

    public void clear(String origin) {

        // Must be a no-op for backward compatibility: see the hidden constructor for reason.

    }



    /**

     * Allow the specified origin to use the Geolocation API.

     * @param origin The origin for which Geolocation API use is allowed.

     * Allows the specified origin to use the Geolocation API.

     *

     * @param origin the origin for which Geolocation API use is allowed

     */

    public void allow(String origin) {

        // Must be a no-op for backward compatibility: see the hidden constructor for reason.

    }



    /**

     * Clear the Geolocation permission state for all origins.

     * Clears the Geolocation permission state for all origins.

     */

    public void clearAll() {

        // Must be a no-op for backward compatibility: see the hidden constructor for reason.

core/java/android/webkit/WebResourceResponse.java

+16 −9
Original line number Diff line number Diff line
@@ -36,9 +36,10 @@ public class WebResourceResponse { 
     * input stream. Callers must implement

     * {@link InputStream#read(byte[]) InputStream.read(byte[])} for the input

     * stream.

     * @param mimeType The resource response's MIME type, for example text/html

     * @param encoding The resource response's encoding

     * @param data The input stream that provides the resource response's data

     *

     * @param mimeType the resource response's MIME type, for example text/html

     * @param encoding the resource response's encoding

     * @param data the input stream that provides the resource response's data

     */

    public WebResourceResponse(String mimeType, String encoding,

            InputStream data) {
@@ -49,7 +50,8 @@ public class WebResourceResponse { 


    /**

     * Sets the resource response's MIME type, for example text/html.

     * @param mimeType The resource response's MIME type

     *

     * @param mimeType the resource response's MIME type

     */

    public void setMimeType(String mimeType) {

        mMimeType = mimeType;
@@ -57,7 +59,8 @@ public class WebResourceResponse { 


    /**

     * Gets the resource response's MIME type.

     * @return The resource response's MIME type

     *

     * @return the resource response's MIME type

     */

    public String getMimeType() {

        return mMimeType;
@@ -66,7 +69,8 @@ public class WebResourceResponse { 
    /**

     * Sets the resource response's encoding, for example UTF-8. This is used

     * to decode the data from the input stream.

     * @param encoding The resource response's encoding

     *

     * @param encoding the resource response's encoding

     */

    public void setEncoding(String encoding) {

        mEncoding = encoding;
@@ -74,7 +78,8 @@ public class WebResourceResponse { 


    /**

     * Gets the resource response's encoding.

     * @return The resource response's encoding

     *

     * @return the resource response's encoding

     */

    public String getEncoding() {

        return mEncoding;
@@ -83,7 +88,8 @@ public class WebResourceResponse { 
    /**

     * Sets the input stream that provides the resource respone's data. Callers

     * must implement {@link InputStream#read(byte[]) InputStream.read(byte[])}.

     * @param data The input stream that provides the resource response's data

     *

     * @param data the input stream that provides the resource response's data

     */

    public void setData(InputStream data) {

        mInputStream = data;
@@ -91,7 +97,8 @@ public class WebResourceResponse { 


    /**

     * Gets the input stream that provides the resource respone's data.

     * @return The input stream that provides the resource response's data

     *

     * @return the input stream that provides the resource response's data

     */

    public InputStream getData() {

        return mInputStream;

core/java/android/webkit/WebSettings.java

+342 −232

File changed.

Preview size limit exceeded, changes collapsed.