Docfixes in IBinder, Context, View, and Intent.
Fix links in @throws clauses, typos, redundant "returns"
and use @code for true + false in returns.
Change-Id: Ic3c4c75d6061732d997a386dc3232475c992c188
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index d8bf6ba..c3d1971 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -306,7 +306,7 @@
}
/**
- * Remove a {@link ComponentCallbacks} objec that was previously registered
+ * Remove a {@link ComponentCallbacks} object that was previously registered
* with {@link #registerComponentCallbacks(ComponentCallbacks)}.
*/
public void unregisterComponentCallbacks(ComponentCallbacks callback) {
@@ -481,7 +481,7 @@
* is always on in apps targetting Gingerbread (Android 2.3) and below, and
* off by default in later versions.
*
- * @return Returns the single SharedPreferences instance that can be used
+ * @return The single {@link SharedPreferences} instance that can be used
* to retrieve and modify the preference values.
*
* @see #MODE_PRIVATE
@@ -499,7 +499,7 @@
* @param name The name of the file to open; can not contain path
* separators.
*
- * @return FileInputStream Resulting input stream.
+ * @return The resulting {@link FileInputStream}.
*
* @see #openFileOutput
* @see #fileList
@@ -520,7 +520,7 @@
* {@link #MODE_WORLD_READABLE} and {@link #MODE_WORLD_WRITEABLE} to control
* permissions.
*
- * @return FileOutputStream Resulting output stream.
+ * @return The resulting {@link FileOutputStream}.
*
* @see #MODE_APPEND
* @see #MODE_PRIVATE
@@ -541,8 +541,8 @@
* @param name The name of the file to delete; can not contain path
* separators.
*
- * @return True if the file was successfully deleted; else
- * false.
+ * @return {@code true} if the file was successfully deleted; else
+ * {@code false}.
*
* @see #openFileInput
* @see #openFileOutput
@@ -558,7 +558,7 @@
* @param name The name of the file for which you would like to get
* its path.
*
- * @return Returns an absolute path to the given file.
+ * @return An absolute path to the given file.
*
* @see #openFileOutput
* @see #getFilesDir
@@ -570,7 +570,7 @@
* Returns the absolute path to the directory on the filesystem where
* files created with {@link #openFileOutput} are stored.
*
- * @return Returns the path of the directory holding application files.
+ * @return The path of the directory holding application files.
*
* @see #openFileOutput
* @see #getFileStreamPath
@@ -644,7 +644,7 @@
* {@link android.os.Environment#DIRECTORY_PICTURES}, or
* {@link android.os.Environment#DIRECTORY_MOVIES}.
*
- * @return Returns the path of the directory holding application files
+ * @return The path of the directory holding application files
* on external storage. Returns null if external storage is not currently
* mounted so it could not ensure the path exists; you will need to call
* this method again when it is available.
@@ -677,7 +677,7 @@
* for the amount of space you consume with cache files, and prune those
* files when exceeding that space.</strong>
*
- * @return Returns the path of the directory holding application cache files.
+ * @return The path of the directory holding application cache files.
*
* @see #openFileOutput
* @see #getFileStreamPath
@@ -718,7 +718,7 @@
* <p>Writing to this path requires the
* {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission.</p>
*
- * @return Returns the path of the directory holding application cache files
+ * @return The path of the directory holding application cache files
* on external storage. Returns null if external storage is not currently
* mounted so it could not ensure the path exists; you will need to call
* this method again when it is available.
@@ -753,7 +753,7 @@
* default operation, {@link #MODE_WORLD_READABLE} and
* {@link #MODE_WORLD_WRITEABLE} to control permissions.
*
- * @return Returns a File object for the requested directory. The directory
+ * @return A {@link File} object for the requested directory. The directory
* will have been created if it does not already exist.
*
* @see #openFileOutput(String, int)
@@ -819,7 +819,7 @@
* @param name The name (unique in the application package) of the
* database.
*
- * @return True if the database was successfully deleted; else false.
+ * @return {@code true} if the database was successfully deleted; else {@code false}.
*
* @see #openOrCreateDatabase
*/
@@ -832,7 +832,7 @@
* @param name The name of the database for which you would like to get
* its path.
*
- * @return Returns an absolute path to the given database.
+ * @return An absolute path to the given database.
*
* @see #openOrCreateDatabase
*/
@@ -910,9 +910,9 @@
*
* @param intent The description of the activity to start.
*
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
*
- * @see {@link #startActivity(Intent, Bundle)}
+ * @see #startActivity(Intent, Bundle)
* @see PackageManager#resolveActivity
*/
public abstract void startActivity(Intent intent);
@@ -924,7 +924,7 @@
* the INTERACT_ACROSS_USERS_FULL permission.
* @param intent The description of the activity to start.
* @param user The UserHandle of the user to start this activity for.
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
* @hide
*/
public void startActivityAsUser(Intent intent, UserHandle user) {
@@ -951,7 +951,7 @@
* for how to build the Bundle supplied here; there are no supported definitions
* for building it manually.
*
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
*
* @see #startActivity(Intent)
* @see PackageManager#resolveActivity
@@ -969,7 +969,7 @@
* for how to build the Bundle supplied here; there are no supported definitions
* for building it manually.
* @param user The UserHandle of the user to start this activity for.
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
* @hide
*/
public void startActivityAsUser(Intent intent, Bundle options, UserHandle userId) {
@@ -982,9 +982,9 @@
*
* @param intents An array of Intents to be started.
*
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
*
- * @see {@link #startActivities(Intent[], Bundle)}
+ * @see #startActivities(Intent[], Bundle)
* @see PackageManager#resolveActivity
*/
public abstract void startActivities(Intent[] intents);
@@ -1008,9 +1008,9 @@
* See {@link android.content.Context#startActivity(Intent, Bundle)
* Context.startActivity(Intent, Bundle)} for more details.
*
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
*
- * @see {@link #startActivities(Intent[])}
+ * @see #startActivities(Intent[])
* @see PackageManager#resolveActivity
*/
public abstract void startActivities(Intent[] intents, Bundle options);
@@ -1036,9 +1036,9 @@
* See {@link android.content.Context#startActivity(Intent, Bundle)
* Context.startActivity(Intent, Bundle)} for more details.
*
- * @throws ActivityNotFoundException
+ * @throws ActivityNotFoundException
*
- * @see {@link #startActivities(Intent[])}
+ * @see #startActivities(Intent[])
* @see PackageManager#resolveActivity
*/
public void startActivitiesAsUser(Intent[] intents, Bundle options, UserHandle userHandle) {
@@ -1604,7 +1604,7 @@
* {@link ComponentName} of the actual service that was started is
* returned; else if the service does not exist null is returned.
*
- * @throws SecurityException
+ * @throws SecurityException
*
* @see #stopService
* @see #bindService
@@ -1632,9 +1632,9 @@
* {@link IntentFilter} published by a service.
*
* @return If there is a service matching the given Intent that is already
- * running, then it is stopped and true is returned; else false is returned.
+ * running, then it is stopped and {@code true} is returned; else {@code false} is returned.
*
- * @throws SecurityException
+ * @throws SecurityException
*
* @see #startService
*/
@@ -1685,11 +1685,11 @@
* {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT},
* {@link #BIND_ALLOW_OOM_MANAGEMENT}, or
* {@link #BIND_WAIVE_PRIORITY}.
- * @return If you have successfully bound to the service, true is returned;
- * false is returned if the connection is not made so you will not
+ * @return If you have successfully bound to the service, {@code true} is returned;
+ * {@code false} is returned if the connection is not made so you will not
* receive the service object.
*
- * @throws SecurityException
+ * @throws SecurityException
*
* @see #unbindService
* @see #startService
@@ -1741,8 +1741,8 @@
* @param arguments Additional optional arguments to pass to the
* instrumentation, or null.
*
- * @return Returns true if the instrumentation was successfully started,
- * else false if it could not be found.
+ * @return {@code true} if the instrumentation was successfully started,
+ * else {@code false} if it could not be found.
*/
public abstract boolean startInstrumentation(ComponentName className,
String profileFile, Bundle arguments);
@@ -2217,7 +2217,7 @@
* and for controlling this device's behavior as a USB device.
*
* @see #getSystemService
- * @see android.harware.usb.UsbManager
+ * @see android.hardware.usb.UsbManager
*/
public static final String USB_SERVICE = "usb";
@@ -2310,7 +2310,7 @@
* @param uid The user ID being checked against. A uid of 0 is the root
* user, which will pass every permission check.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the given
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the given
* pid/uid is allowed that permission, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2332,7 +2332,7 @@
*
* @param permission The name of the permission being checked.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the calling
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the calling
* pid/uid is allowed that permission, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2350,7 +2350,7 @@
*
* @param permission The name of the permission being checked.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the calling
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the calling
* pid/uid is allowed that permission, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2482,7 +2482,7 @@
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
* {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the given
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the given
* pid/uid is allowed to access that uri, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2505,7 +2505,7 @@
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
* {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the caller
* is allowed to access that uri, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2524,7 +2524,7 @@
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
* {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the caller
* is allowed to access that uri, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*
@@ -2550,7 +2550,7 @@
* {@link Intent#FLAG_GRANT_READ_URI_PERMISSION Intent.FLAG_GRANT_READ_URI_PERMISSION} or
* {@link Intent#FLAG_GRANT_WRITE_URI_PERMISSION Intent.FLAG_GRANT_WRITE_URI_PERMISSION}.
*
- * @return Returns {@link PackageManager#PERMISSION_GRANTED} if the caller
+ * @return {@link PackageManager#PERMISSION_GRANTED} if the caller
* is allowed to access that uri or holds one of the given permissions, or
* {@link PackageManager#PERMISSION_DENIED} if it is not.
*/
@@ -2694,11 +2694,11 @@
* @param flags Option flags, one of {@link #CONTEXT_INCLUDE_CODE}
* or {@link #CONTEXT_IGNORE_SECURITY}.
*
- * @return A Context for the application.
+ * @return A {@link Context} for the application.
*
- * @throws java.lang.SecurityException
+ * @throws SecurityException
* @throws PackageManager.NameNotFoundException if there is no application with
- * the given package name
+ * the given package name.
*/
public abstract Context createPackageContext(String packageName,
int flags) throws PackageManager.NameNotFoundException;
@@ -2735,7 +2735,7 @@
* orientation change), the resources of this context will also change except
* for those that have been explicitly overridden with a value here.
*
- * @return A Context with the given configuration override.
+ * @return A {@link Context} with the given configuration override.
*/
public abstract Context createConfigurationContext(Configuration overrideConfiguration);
@@ -2755,7 +2755,7 @@
* for whose metrics the Context's resources should be tailored and upon which
* new windows should be shown.
*
- * @return A Context for the display.
+ * @return A {@link Context} for the display.
*/
public abstract Context createDisplayContext(Display display);
@@ -2773,7 +2773,7 @@
/**
* Indicates whether this Context is restricted.
*
- * @return True if this Context is restricted, false otherwise.
+ * @return {@code true} if this Context is restricted, {@code false} otherwise.
*
* @see #CONTEXT_RESTRICTED
*/
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index bda7112..62c8d58 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -1458,7 +1458,7 @@
/**
* Broadcast Action: The current time has changed. Sent every
* minute. You can <em>not</em> receive this through components declared
- * in manifests, only by exlicitly registering for it with
+ * in manifests, only by explicitly registering for it with
* {@link Context#registerReceiver(BroadcastReceiver, IntentFilter)
* Context.registerReceiver()}.
*
@@ -2658,7 +2658,7 @@
* Set if the activity should be an option for the default action
* (center press) to perform on a piece of data. Setting this will
* hide from the user any activities without it set when performing an
- * action on some data. Note that this is normal -not- set in the
+ * action on some data. Note that this is normally -not- set in the
* Intent when initiating an action -- it is for use in intent filters
* specified in packages.
*/
diff --git a/core/java/android/os/IBinder.java b/core/java/android/os/IBinder.java
index b7bc45f..a2432d6 100644
--- a/core/java/android/os/IBinder.java
+++ b/core/java/android/os/IBinder.java
@@ -238,7 +238,7 @@
* <p>You will only receive death notifications for remote binders,
* as local binders by definition can't die without you dying as well.
*
- * @throws Throws {@link RemoteException} if the target IBinder's
+ * @throws RemoteException if the target IBinder's
* process has already died.
*
* @see #unlinkToDeath
@@ -251,13 +251,13 @@
* The recipient will no longer be called if this object
* dies.
*
- * @return Returns true if the <var>recipient</var> is successfully
+ * @return {@code true} if the <var>recipient</var> is successfully
* unlinked, assuring you that its
* {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method
- * will not be called. Returns false if the target IBinder has already
+ * will not be called; {@code false} if the target IBinder has already
* died, meaning the method has been (or soon will be) called.
*
- * @throws Throws {@link java.util.NoSuchElementException} if the given
+ * @throws java.util.NoSuchElementException if the given
* <var>recipient</var> has not been registered with the IBinder, and
* the IBinder is still alive. Note that if the <var>recipient</var>
* was never registered, but the IBinder has already died, then this
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index bcd8d5c..7447d1b 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -5689,7 +5689,7 @@
* which you would like to ensure are not being covered.
*
* <p>The default implementation of this method simply applies the content
- * inset's to the view's padding, consuming that content (modifying the
+ * insets to the view's padding, consuming that content (modifying the
* insets to be 0), and returning true. This behavior is off by default, but can
* be enabled through {@link #setFitsSystemWindows(boolean)}.
*
@@ -5726,8 +5726,8 @@
* {@link android.os.Build.VERSION_CODES#JELLY_BEAN} you must not modify
* the insets or else you and Android will be unhappy.
*
- * @return Return true if this view applied the insets and it should not
- * continue propagating further down the hierarchy, false otherwise.
+ * @return {@code true} if this view applied the insets and it should not
+ * continue propagating further down the hierarchy, {@code false} otherwise.
* @see #getFitsSystemWindows()
* @see #setFitsSystemWindows(boolean)
* @see #setSystemUiVisibility(int)
@@ -5798,15 +5798,15 @@
}
/**
- * Check for state of {@link #setFitsSystemWindows(boolean). If this method
- * returns true, the default implementation of {@link #fitSystemWindows(Rect)}
+ * Check for state of {@link #setFitsSystemWindows(boolean)}. If this method
+ * returns {@code true}, the default implementation of {@link #fitSystemWindows(Rect)}
* will be executed.
*
- * @return Returns true if the default implementation of
+ * @return {@code true} if the default implementation of
* {@link #fitSystemWindows(Rect)} will be executed.
*
* @attr ref android.R.styleable#View_fitsSystemWindows
- * @see #setFitsSystemWindows()
+ * @see #setFitsSystemWindows(boolean)
* @see #fitSystemWindows(Rect)
* @see #setSystemUiVisibility(int)
*/
@@ -16512,7 +16512,7 @@
/**
* Override to find out when the window's requested system UI visibility
* has changed, that is the value returned by {@link #getWindowSystemUiVisibility()}.
- * This is different from the callbacks recieved through
+ * This is different from the callbacks received through
* {@link #setOnSystemUiVisibilityChangeListener(OnSystemUiVisibilityChangeListener)}
* in that this is only telling you about the local request of the window,
* not the actual values applied by the system.