Merge "Binder: correction of javadoc formatting" am: a83307fbd8 am: 0784bb4330 am: 7ebf0a92ff am: cd045eb0ff

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1877757

Change-Id: Id40a2d6958a2c4456f0dc299c3c1fadf248b1d29

core/java/android/os/Binder.java

@@ -63,7 +63,7 @@ import java.lang.reflect.Modifier;
  * To use this correctly, you must be doing so within the context of a top-level
  * application component (a {@link android.app.Service}, {@link android.app.Activity},
  * or {@link android.content.ContentProvider}) that lets the system know your process
- * should remain running.</p>
+ * should remain running.
  *
  * <p>You must keep in mind the situations in which your process
  * could go away, and thus require that you later re-create a new Binder and re-attach
@@ -73,7 +73,7 @@ import java.lang.reflect.Modifier;
  * create a new Binder and hand it back to the correct place again; you need to be
  * aware that your process may be started for another reason (for example to receive
  * a broadcast) that will not involve re-creating the activity and thus run its code
- * to create a new Binder.</p>
+ * to create a new Binder.
  *
  * @see IBinder
  */
@@ -94,14 +94,15 @@ public class Binder implements IBinder {
     /**
      * Value to represents that a calling work source is not set.
      *
-     * This constatnt needs to be kept in sync with IPCThreadState::kUnsetWorkSource.
+     * <p>This constant needs to be kept in sync with IPCThreadState::kUnsetWorkSource.
      *
      * @hide
      */
     public static final int UNSET_WORKSOURCE = -1;
 
     /**
-     * Control whether dump() calls are allowed.
+     * Control whether {@link #dump(FileDescriptor, PrintWriter, String[]) dump()}
+     * calls are allowed.
      */
     private static volatile String sDumpDisabled = null;
 
@@ -188,7 +189,7 @@ public class Binder implements IBinder {
         sObserver = observer;
     }
 
-    /** {@hide} */
+    /** @hide */
     static volatile boolean sWarnOnBlocking = false;
 
     /**
@@ -207,8 +208,8 @@ public class Binder implements IBinder {
     /**
      * Allow blocking calls on the given interface, overriding the requested
      * value of {@link #setWarnOnBlocking(boolean)}.
-     * <p>
+     *
-     * This should only be rarely called when you are <em>absolutely sure</em>
+     * <p>This should only be rarely called when you are <em>absolutely sure</em>
      * the remote interface is a built-in system component that can never be
      * upgraded. In particular, this <em>must never</em> be called for
      * interfaces hosted by package that could be upgraded or replaced,
@@ -258,7 +259,9 @@ public class Binder implements IBinder {
             ThreadLocal.withInitial(() -> sWarnOnBlocking);
 
     /**
-     * Allow blocking calls for the current thread.  See {@link #allowBlocking}.
+     * Allow blocking calls for the current thread.
+     *
+     * @see {@link #allowBlocking}.
      *
      * @hide
      */
@@ -267,7 +270,9 @@ public class Binder implements IBinder {
     }
 
     /**
-     * Reset the current thread to the default blocking behavior.  See {@link #defaultBlocking}.
+     * Reset the current thread to the default blocking behavior.
+     *
+     * @see {@link #defaultBlocking}.
      *
      * @hide
      */
@@ -286,10 +291,10 @@ public class Binder implements IBinder {
 
     /**
      * Return the ID of the process that sent you the current transaction
-     * that is being processed.  This pid can be used with higher-level
+     * that is being processed. This PID can be used with higher-level
      * system services to determine its identity and check permissions.
      * If the current thread is not currently executing an incoming transaction,
-     * then its own pid is returned.
+     * then its own PID is returned.
      *
      * Warning: oneway transactions do not receive PID.
      */
@@ -297,11 +302,11 @@ public class Binder implements IBinder {
     public static final native int getCallingPid();
 
     /**
-     * Return the Linux uid assigned to the process that sent you the
+     * Return the Linux UID assigned to the process that sent you the
-     * current transaction that is being processed.  This uid can be used with
+     * current transaction that is being processed. This UID can be used with
      * higher-level system services to determine its identity and check
      * permissions. If the current thread is not currently executing an
-     * incoming transaction, then its own uid is returned.
+     * incoming transaction, then its own UID is returned.
      */
     @CriticalNative
     public static final native int getCallingUid();
@@ -316,7 +321,7 @@ public class Binder implements IBinder {
     public static final native boolean isDirectlyHandlingTransaction();
 
     /**
-     * Return the Linux uid assigned to the process that sent the transaction
+     * Return the Linux UID assigned to the process that sent the transaction
      * currently being processed.
      *
      * @throws IllegalStateException if the current thread is not currently
@@ -335,8 +340,10 @@ public class Binder implements IBinder {
      * current transaction that is being processed. This is the user
      * of the caller. It is distinct from {@link #getCallingUid()} in that a
      * particular user will have multiple distinct apps running under it each
-     * with their own uid.  If the current thread is not currently executing an
+     * with their own UID. If the current thread is not currently executing an
      * incoming transaction, then its own UserHandle is returned.
+     *
+     * @see UserHandle
      */
     public static final @NonNull UserHandle getCallingUserHandle() {
         return UserHandle.of(UserHandle.getUserId(getCallingUid()));
@@ -376,10 +383,10 @@ public class Binder implements IBinder {
 
     /**
      * Convenience method for running the provided action enclosed in
-     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity}
+     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity}.
      *
-     * Any exception thrown by the given action will be caught and rethrown after the call to
+     * <p>Any exception thrown by the given action will be caught and
-     * {@link #restoreCallingIdentity}
+     * rethrown after the call to {@link #restoreCallingIdentity}.
      *
      * @hide
      */
@@ -400,10 +407,10 @@ public class Binder implements IBinder {
 
     /**
      * Convenience method for running the provided action enclosed in
-     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity} returning the result
+     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity} returning the result.
      *
-     * Any exception thrown by the given action will be caught and rethrown after the call to
+     * <p>Any exception thrown by the given action will be caught and rethrown after
-     * {@link #restoreCallingIdentity}
+     * the call to {@link #restoreCallingIdentity}.
      *
      * @hide
      */
@@ -434,6 +441,7 @@ public class Binder implements IBinder {
      * native-only code on Dalvik.
      *
      * @see StrictMode
+     *
      * @hide
      */
     @CriticalNative
@@ -443,6 +451,7 @@ public class Binder implements IBinder {
      * Gets the current native thread-local StrictMode policy mask.
      *
      * @see #setThreadStrictModePolicy
+     *
      * @hide
      */
     @CriticalNative
@@ -459,7 +468,7 @@ public class Binder implements IBinder {
      * reasons, we only support one UID. This UID represents the original user responsible for the
      * binder calls.
      *
-     * <p>{@link Binder#restoreCallingWorkSource(long)} must always be called after setting the
+     * <p>{@link #restoreCallingWorkSource(long)} must always be called after setting the
      * worksource.
      *
      * <p>A typical use case would be
@@ -477,16 +486,16 @@ public class Binder implements IBinder {
      *
      * @param workSource The original UID responsible for the binder call.
      * @return token to restore original work source.
-     **/
+     */
     @CriticalNative
     public static final native long setCallingWorkSourceUid(int workSource);
 
     /**
      * Returns the work source set by the caller.
      *
-     * Unlike {@link Binder#getCallingUid()}, this result of this method cannot be trusted. The
+     * <p>Unlike {@link #getCallingUid()}, this result of this method cannot be trusted. The
      * caller can set the value to whatever they want. Only use this value if you trust the calling
-     * uid.
+     * UID.
      *
      * @return The original UID responsible for the binder transaction.
      */
@@ -499,7 +508,7 @@ public class Binder implements IBinder {
      * <p>The work source will be propagated for future outgoing binder transactions
      * executed on this thread.
      *
-     * <p>{@link Binder#restoreCallingWorkSource(long)} must always be called after clearing the
+     * <p>{@link #restoreCallingWorkSource(long)} must always be called after clearing the
      * worksource.
      *
      * <p>A typical use case would be
@@ -513,13 +522,13 @@ public class Binder implements IBinder {
      * </pre>
      *
      * @return token to restore original work source.
-     **/
+     */
     @CriticalNative
     public static final native long clearCallingWorkSource();
 
     /**
      * Restores the work source on this thread using a token returned by
-     * {@link #setCallingWorkSourceUid(int) or {@link clearCallingWorkSource()}.
+     * {@link #setCallingWorkSourceUid(int)} or {@link #clearCallingWorkSource()}.
      *
      * <p>A typical use case would be
      * <pre>
@@ -530,7 +539,7 @@ public class Binder implements IBinder {
      *   Binder.restoreCallingWorkSource(token);
      * }
      * </pre>
-     **/
+     */
     @CriticalNative
     public static final native void restoreCallingWorkSource(long token);
 
@@ -553,7 +562,7 @@ public class Binder implements IBinder {
      * Use a VINTF-stability binder w/o VINTF requirements. Should be called
      * on a binder before it is sent out of process.
      *
-     * This must be called before the object is sent to another process.
+     * <p>This must be called before the object is sent to another process.
      *
      * @hide
      */
@@ -579,6 +588,7 @@ public class Binder implements IBinder {
 
     /**
      * Returns true if the specified interface is a proxy.
+     *
      * @hide
      */
     public static final boolean isProxy(IInterface iface) {
@@ -588,6 +598,7 @@ public class Binder implements IBinder {
     /**
      * Call blocks until the number of executing binder threads is less
      * than the maximum number of binder threads allowed for this process.
+     *
      * @hide
      */
     public static final native void blockUntilThreadAvailable();
@@ -595,7 +606,7 @@ public class Binder implements IBinder {
     /**
      * Default constructor just initializes the object.
      *
-     * If you're creating a Binder token (a Binder object without an attached interface),
+     * <p>If you're creating a Binder token (a Binder object without an attached interface),
      * you should use {@link #Binder(String)} instead.
      */
     public Binder() {
@@ -605,7 +616,7 @@ public class Binder implements IBinder {
     /**
      * Constructor for creating a raw Binder object (token) along with a descriptor.
      *
-     * The descriptor of binder objects usually specifies the interface they are implementing.
+     * <p>The descriptor of binder objects usually specifies the interface they are implementing.
      * In case of binder tokens, no interface is implemented, and the descriptor can be used
      * as a sort of tag to help identify the binder token. This will help identify remote
      * references to these objects more easily when debugging.
@@ -631,9 +642,9 @@ public class Binder implements IBinder {
 
     /**
      * Convenience method for associating a specific interface with the Binder.
-     * After calling, queryLocalInterface() will be implemented for you
+     * After calling, {@link #queryLocalInterface(String) queryLocalInterface()}
-     * to return the given owner IInterface when the corresponding
+     * will be implemented for you to return the given owner IInterface when
-     * descriptor is requested.
+     * the corresponding descriptor is requested.
      */
     public void attachInterface(@Nullable IInterface owner, @Nullable String descriptor) {
         mOwner = owner;
@@ -666,8 +677,8 @@ public class Binder implements IBinder {
     }
 
     /**
-     * Use information supplied to attachInterface() to return the
+     * Use information supplied to {@link #attachInterface attachInterface()}
-     * associated IInterface if it matches the requested
+     * to return the associated {@link IInterface} if it matches the requested
      * descriptor.
      */
     public @Nullable IInterface queryLocalInterface(@NonNull String descriptor) {
@@ -682,10 +693,11 @@ public class Binder implements IBinder {
      * process watchdog to disable incoming dump calls while it has detecting the system
      * is hung and is reporting that back to the activity controller. This is to
      * prevent the controller from getting hung up on bug reports at this point.
-     * @hide
      *
      * @param msg The message to show instead of the dump; if null, dumps are
      * re-enabled.
+     *
+     * @hide
      */
     public static void setDumpDisabled(String msg) {
         sDumpDisabled = msg;
@@ -694,7 +706,8 @@ public class Binder implements IBinder {
     /**
      * Listener to be notified about each proxy-side binder call.
      *
-     * See {@link setProxyTransactListener}.
+     * @see {@link #setProxyTransactListener}.
+     *
      * @hide
      */
     @SystemApi
@@ -702,7 +715,8 @@ public class Binder implements IBinder {
         /**
          * Called before onTransact.
          *
-         * @return an object that will be passed back to #onTransactEnded (or null).
+         * @return an object that will be passed back to {@link #onTransactEnded} (or null).,
+         *
          * @hide
          */
         @Nullable
@@ -713,15 +727,15 @@ public class Binder implements IBinder {
         /**
          * Called before onTransact.
          *
-         * @return an object that will be passed back to #onTransactEnded (or null).
+         * @return an object that will be passed back to {@link #onTransactEnded} (or null).
          */
         @Nullable
         Object onTransactStarted(@NonNull IBinder binder, int transactionCode);
 
         /**
-         * Called after onTranact (even when an exception is thrown).
+         * Called after onTransact (even when an exception is thrown).
          *
-         * @param session The object return by #onTransactStarted.
+         * @param session The object return by {@link #onTransactStarted}.
          */
         void onTransactEnded(@Nullable Object session);
     }
@@ -732,16 +746,17 @@ public class Binder implements IBinder {
      * <li>By default, this listener will propagate the worksource if the outgoing call happens on
      * the same thread as the incoming binder call.
      * <li>Custom attribution can be done by calling {@link ThreadLocalWorkSource#setUid(int)}.
+     *
      * @hide
      */
     public static class PropagateWorkSourceTransactListener implements ProxyTransactListener {
         @Override
         public Object onTransactStarted(IBinder binder, int transactionCode) {
-           // Note that {@link Binder#getCallingUid()} is already set to the UID of the current
+            // Note that {@link #getCallingUid()} is already set to the UID of the current
             // process when this method is called.
             //
-           // We use ThreadLocalWorkSource instead. It also allows feature owners to set
+            // We use {@link ThreadLocalWorkSource} instead. It also allows feature owners to set
-           // {@link ThreadLocalWorkSource#set(int) manually to attribute resources to a UID.
+            // {@link ThreadLocalWorkSource#set(int)} manually to attribute resources to a UID.
             int uid = ThreadLocalWorkSource.getUid();
             if (uid != ThreadLocalWorkSource.UID_NONE) {
                 return Binder.setCallingWorkSourceUid(uid);
@@ -770,6 +785,7 @@ public class Binder implements IBinder {
      * <li>The listener is called on the critical path of the binder transaction so be careful about
      * performance.
      * <li>Never execute another binder transaction inside the listener.
+     *
      * @hide
      */
     @SystemApi
@@ -786,11 +802,10 @@ public class Binder implements IBinder {
      * <p>Implementations that are returning a result should generally use
      * {@link Parcel#writeNoException() Parcel.writeNoException} and
      * {@link Parcel#writeException(Exception) Parcel.writeException} to propagate
-     * exceptions back to the caller.</p>
+     * exceptions back to the caller.
      *
-     * @param code The action to perform.  This should
+     * @param code The action to perform. This should be a number between
-     * be a number between {@link #FIRST_CALL_TRANSACTION} and
+     * {@link #FIRST_CALL_TRANSACTION} and {@link #LAST_CALL_TRANSACTION}.
-     * {@link #LAST_CALL_TRANSACTION}.
      * @param data Marshalled data being received from the caller.
      * @param reply If the caller is expecting a result back, it should be marshalled
      * in to here.
@@ -856,10 +871,12 @@ public class Binder implements IBinder {
      * Resolves a transaction code to a human readable name.
      *
      * <p>Default implementation is a stub that returns null.
+     *
      * <p>AIDL generated code will return the original method name.
      *
      * @param transactionCode The code to resolve.
      * @return A human readable name.
+     *
      * @hide
      */
     public @Nullable String getTransactionName(int transactionCode) {
@@ -941,6 +958,7 @@ public class Binder implements IBinder {
      * @param callback Callback through which to interact with the invoking shell.
      * @param resultReceiver Called when the command has finished executing, with the result code.
      * @throws RemoteException
+     *
      * @hide
      */
     public void shellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,
@@ -958,7 +976,8 @@ public class Binder implements IBinder {
      *
      * <p class="caution">Note: no permission checking is done before calling this method; you must
      * apply any security checks as appropriate for the command being executed.
-     * Consider using {@link ShellCommand} to help in the implementation.</p>
+     * Consider using {@link ShellCommand} to help in the implementation.
+     *
      * @hide
      */
     public void onShellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,
@@ -1013,7 +1032,7 @@ public class Binder implements IBinder {
      * System services can implement this method to implement ADB shell commands.
      *
      * <p>A system binder service can implement it to handle shell commands on ADB. For example,
-     * the Job Scheduler service implements it to handle <code>adb shell cmd jobscheduler</code>.
+     * the Job Scheduler service implements it to handle {@code adb shell cmd jobscheduler}.
      *
      * <p>Commands are only executable by ADB shell; i.e. only {@link Process#SHELL_UID} and
      * {@link Process#ROOT_UID} can call them.
@@ -1023,7 +1042,7 @@ public class Binder implements IBinder {
      * @param err standard error
      * @param args arguments passed to the command. Can be empty. The first argument is typically
      * a subcommand, such as {@code run} for {@code adb shell cmd jobscheduler run}.
-     * @return the status code returned from the <code>cmd</code> command.
+     * @return the status code returned from the {@code cmd} command.
      *
      * @hide
      */
@@ -1083,7 +1102,7 @@ public class Binder implements IBinder {
 
     static void checkParcel(IBinder obj, int code, Parcel parcel, String msg) {
         if (CHECK_PARCEL_SIZE && parcel.dataSize() >= 800*1024) {
-            // Trying to send > 800k, this is way too much
+            // Trying to send > 800k, this is way too much.
             StringBuilder sb = new StringBuilder();
             sb.append(msg);
             sb.append(": on ");
@@ -1107,7 +1126,7 @@ public class Binder implements IBinder {
     private static native long getNativeBBinderHolder();
 
     /**
-     * By default, we use the calling uid since we can always trust it.
+     * By default, we use the calling UID since we can always trust it.
      */
     private static volatile BinderInternal.WorkSourceProvider sWorkSourceProvider =
             (x) -> Binder.getCallingUid();
@@ -1122,6 +1141,7 @@ public class Binder implements IBinder {
      * <li>The callback is called on the critical path of the binder transaction so be careful about
      * performance.
      * <li>Never execute another binder transaction inside the callback.
+     *
      * @hide
      */
     public static void setWorkSourceProvider(BinderInternal.WorkSourceProvider workSourceProvider) {
@@ -1131,12 +1151,12 @@ public class Binder implements IBinder {
         sWorkSourceProvider = workSourceProvider;
     }
 
-    // Entry point from android_util_Binder.cpp's onTransact
+    // Entry point from android_util_Binder.cpp's onTransact.
     @UnsupportedAppUsage
     private boolean execTransact(int code, long dataObj, long replyObj,
             int flags) {
         // At that point, the parcel request headers haven't been parsed so we do not know what
-        // WorkSource the caller has set. Use calling uid as the default.
+        // {@link WorkSource} the caller has set. Use calling UID as the default.
         final int callingUid = Binder.getCallingUid();
         final long origWorkSource = ThreadLocalWorkSource.setUid(callingUid);
         try {
@@ -1154,17 +1174,18 @@ public class Binder implements IBinder {
                 observer != null ? observer.callStarted(this, code, UNSET_WORKSOURCE) : null;
         Parcel data = Parcel.obtain(dataObj);
         Parcel reply = Parcel.obtain(replyObj);
-        // theoretically, we should call transact, which will call onTransact,
+        // Theoretically, we should call transact, which will call onTransact,
         // but all that does is rewind it, and we just got these from an IPC,
         // so we'll just call it directly.
         boolean res;
         // Log any exceptions as warnings, don't silently suppress them.
-        // If the call was FLAG_ONEWAY then these exceptions disappear into the ether.
+        // If the call was {@link IBinder#FLAG_ONEWAY} then these exceptions
+        // disappear into the ether.
         final boolean tracingEnabled = Binder.isTracingEnabled();
         try {
             final BinderCallHeavyHitterWatcher heavyHitterWatcher = sHeavyHitterWatcher;
             if (heavyHitterWatcher != null) {
-                // Notify the heavy hitter watcher, if it's enabled
+                // Notify the heavy hitter watcher, if it's enabled.
                 heavyHitterWatcher.onTransaction(callingUid, getClass(), code);
             }
             if (tracingEnabled) {
@@ -1197,7 +1218,7 @@ public class Binder implements IBinder {
                     Log.w(TAG, "Caught a RuntimeException from the binder stub implementation.", e);
                 }
             } else {
-                // Clear the parcel before writing the exception
+                // Clear the parcel before writing the exception.
                 reply.setDataSize(0);
                 reply.setDataPosition(0);
                 reply.writeException(e);
@@ -1209,7 +1230,7 @@ public class Binder implements IBinder {
             }
             if (observer != null) {
                 // The parcel RPC headers have been called during onTransact so we can now access
-                // the worksource uid from the parcel.
+                // the worksource UID from the parcel.
                 final int workSourceUid = sWorkSourceProvider.resolveWorkSourceUid(
                         data.readCallingWorkSourceUid());
                 observer.callEnded(callSession, data.dataSize(), reply.dataSize(), workSourceUid);