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

Commit 30e06bb6 authored by Jeff Sharkey's avatar Jeff Sharkey
Browse files

Even more auto-doc work. 

Update docs based on what new lint detector found.  Add new @IntDef
to parameters or methods returning constants or flags, and add
@RequiresPermission to methods mentioning permissions.

Test: make -j32 offline-sdk-docs
Bug: 37526420
Change-Id: I7f640f7883fcb66b911a52ae93b83f77306571ec
parent 4d23f258

core/java/android/annotation/BroadcastBehavior.java

+5 −0
Original line number Diff line number Diff line
@@ -53,4 +53,9 @@ public @interface BroadcastBehavior { 
     * @see Intent#FLAG_RECEIVER_INCLUDE_BACKGROUND

     */

    boolean includeBackground() default false;



    /**

     * This broadcast is protected and can only be sent by the OS.

     */

    boolean protectedBroadcast() default false;

}

core/java/android/app/Activity.java

+1 −1
Original line number Diff line number Diff line
@@ -5844,7 +5844,7 @@ public class Activity extends ContextThemeWrapper 
     * @return Returns the single SharedPreferences instance that can be used

     *         to retrieve and modify the preference values.

     */

    public SharedPreferences getPreferences(int mode) {

    public SharedPreferences getPreferences(@Context.PreferencesMode int mode) {

        return getSharedPreferences(getLocalClassName(), mode);

    }

core/java/android/app/ActivityManager.java

+18 −15
Original line number Diff line number Diff line
@@ -2350,6 +2350,14 @@ public class ActivityManager { 
        }

    }



    /** @hide */

    @IntDef(flag = true, prefix = { "MOVE_TASK_" }, value = {

            MOVE_TASK_WITH_HOME,

            MOVE_TASK_NO_USER_ACTION,

    })

    @Retention(RetentionPolicy.SOURCE)

    public @interface MoveTaskFlags {}



    /**

     * Flag for {@link #moveTaskToFront(int, int)}: also move the "home"

     * activity along with the task, so it is positioned immediately behind
@@ -2370,28 +2378,26 @@ public class ActivityManager { 
     *

     * @param taskId The identifier of the task to be moved, as found in

     * {@link RunningTaskInfo} or {@link RecentTaskInfo}.

     * @param flags Additional operational flags, 0 or more of

     * {@link #MOVE_TASK_WITH_HOME}, {@link #MOVE_TASK_NO_USER_ACTION}.

     * @param flags Additional operational flags.

     */

    public void moveTaskToFront(int taskId, int flags) {

    @RequiresPermission(android.Manifest.permission.REORDER_TASKS)

    public void moveTaskToFront(int taskId, @MoveTaskFlags int flags) {

        moveTaskToFront(taskId, flags, null);

    }



    /**

     * Ask that the task associated with a given task ID be moved to the

     * front of the stack, so it is now visible to the user.  Requires that

     * the caller hold permission {@link android.Manifest.permission#REORDER_TASKS}

     * or a SecurityException will be thrown.

     * front of the stack, so it is now visible to the user.

     *

     * @param taskId The identifier of the task to be moved, as found in

     * {@link RunningTaskInfo} or {@link RecentTaskInfo}.

     * @param flags Additional operational flags, 0 or more of

     * {@link #MOVE_TASK_WITH_HOME}, {@link #MOVE_TASK_NO_USER_ACTION}.

     * @param flags Additional operational flags.

     * @param options Additional options for the operation, either null or

     * as per {@link Context#startActivity(Intent, android.os.Bundle)

     * Context.startActivity(Intent, Bundle)}.

     */

    public void moveTaskToFront(int taskId, int flags, Bundle options) {

    @RequiresPermission(android.Manifest.permission.REORDER_TASKS)

    public void moveTaskToFront(int taskId, @MoveTaskFlags int flags, Bundle options) {

        try {

            getService().moveTaskToFront(taskId, flags, options);

        } catch (RemoteException e) {
@@ -3637,13 +3643,10 @@ public class ActivityManager { 
     * processes to reclaim memory; the system will take care of restarting

     * these processes in the future as needed.

     *

     * <p>You must hold the permission

     * {@link android.Manifest.permission#KILL_BACKGROUND_PROCESSES} to be able to

     * call this method.

     *

     * @param packageName The name of the package whose processes are to

     * be killed.

     */

    @RequiresPermission(Manifest.permission.KILL_BACKGROUND_PROCESSES)

    public void killBackgroundProcesses(String packageName) {

        try {

            getService().killBackgroundProcesses(packageName,
@@ -4015,13 +4018,13 @@ public class ActivityManager { 
     * Perform a system dump of various state associated with the given application

     * package name.  This call blocks while the dump is being performed, so should

     * not be done on a UI thread.  The data will be written to the given file

     * descriptor as text.  An application must hold the

     * {@link android.Manifest.permission#DUMP} permission to make this call.

     * descriptor as text.

     * @param fd The file descriptor that the dump should be written to.  The file

     * descriptor is <em>not</em> closed by this function; the caller continues to

     * own it.

     * @param packageName The name of the package that is to be dumped.

     */

    @RequiresPermission(Manifest.permission.DUMP)

    public void dumpPackageState(FileDescriptor fd, String packageName) {

        dumpPackageStateStatic(fd, packageName);

    }

core/java/android/app/AlarmManager.java

+48 −38
Original line number Diff line number Diff line
@@ -16,6 +16,7 @@ 


package android.app;



import android.annotation.IntDef;

import android.annotation.SdkConstant;

import android.annotation.SystemApi;

import android.content.Context;
@@ -34,6 +35,8 @@ import android.util.Log; 
import libcore.util.ZoneInfoDB;



import java.io.IOException;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;



/**

 * This class provides access to the system alarm services.  These allow you
@@ -78,6 +81,16 @@ import java.io.IOException; 
public class AlarmManager {

    private static final String TAG = "AlarmManager";



    /** @hide */

    @IntDef(prefix = { "RTC", "ELAPSED" }, value = {

            RTC_WAKEUP,

            RTC,

            ELAPSED_REALTIME_WAKEUP,

            ELAPSED_REALTIME,

    })

    @Retention(RetentionPolicy.SOURCE)

    public @interface AlarmType {}



    /**

     * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()}

     * (wall clock time in UTC), which will wake up the device when
@@ -311,8 +324,7 @@ public class AlarmManager { 
     * will be treated as exact.

     * </div>

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should go

     * off, using the appropriate clock (depending on the alarm type).

     * @param operation Action to perform when the alarm goes off;
@@ -332,7 +344,7 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void set(int type, long triggerAtMillis, PendingIntent operation) {

    public void set(@AlarmType int type, long triggerAtMillis, PendingIntent operation) {

        setImpl(type, triggerAtMillis, legacyExactLength(), 0, 0, operation, null, null,

                null, null, null);

    }
@@ -346,8 +358,7 @@ public class AlarmManager { 
     * invoked via the specified target Handler, or on the application's main looper

     * if {@code null} is passed as the {@code targetHandler} parameter.

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *         {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should go

     *         off, using the appropriate clock (depending on the alarm type).

     * @param tag string describing the alarm, used for logging and battery-use
@@ -360,7 +371,7 @@ public class AlarmManager { 
     * @param targetHandler {@link Handler} on which to execute the listener's onAlarm()

     *         callback, or {@code null} to run that callback on the main looper.

     */

    public void set(int type, long triggerAtMillis, String tag, OnAlarmListener listener,

    public void set(@AlarmType int type, long triggerAtMillis, String tag, OnAlarmListener listener,

            Handler targetHandler) {

        setImpl(type, triggerAtMillis, legacyExactLength(), 0, 0, null, listener, tag,

                targetHandler, null, null);
@@ -399,8 +410,7 @@ public class AlarmManager { 
     * whose {@code targetSdkVersion} is earlier than API 19 will continue to have all

     * of their alarms, including repeating alarms, treated as exact.

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should first

     * go off, using the appropriate clock (depending on the alarm type).

     * @param intervalMillis interval in milliseconds between subsequent repeats
@@ -422,7 +432,7 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void setRepeating(int type, long triggerAtMillis,

    public void setRepeating(@AlarmType int type, long triggerAtMillis,

            long intervalMillis, PendingIntent operation) {

        setImpl(type, triggerAtMillis, legacyExactLength(), intervalMillis, 0, operation,

                null, null, null, null, null);
@@ -448,8 +458,7 @@ public class AlarmManager { 
     * at precisely-specified times with no acceptable variation, applications can use

     * {@link #setExact(int, long, PendingIntent)}.

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param windowStartMillis The earliest time, in milliseconds, that the alarm should

     *        be delivered, expressed in the appropriate clock's units (depending on the alarm

     *        type).
@@ -473,7 +482,7 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void setWindow(int type, long windowStartMillis, long windowLengthMillis,

    public void setWindow(@AlarmType int type, long windowStartMillis, long windowLengthMillis,

            PendingIntent operation) {

        setImpl(type, windowStartMillis, windowLengthMillis, 0, 0, operation,

                null, null, null, null, null);
@@ -488,7 +497,7 @@ public class AlarmManager { 
     * invoked via the specified target Handler, or on the application's main looper

     * if {@code null} is passed as the {@code targetHandler} parameter.

     */

    public void setWindow(int type, long windowStartMillis, long windowLengthMillis,

    public void setWindow(@AlarmType int type, long windowStartMillis, long windowLengthMillis,

            String tag, OnAlarmListener listener, Handler targetHandler) {

        setImpl(type, windowStartMillis, windowLengthMillis, 0, 0, null, listener, tag,

                targetHandler, null, null);
@@ -508,8 +517,7 @@ public class AlarmManager { 
     * scheduled as exact.  Applications are strongly discouraged from using exact

     * alarms unnecessarily as they reduce the OS's ability to minimize battery use.

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should go

     *        off, using the appropriate clock (depending on the alarm type).

     * @param operation Action to perform when the alarm goes off;
@@ -528,7 +536,7 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void setExact(int type, long triggerAtMillis, PendingIntent operation) {

    public void setExact(@AlarmType int type, long triggerAtMillis, PendingIntent operation) {

        setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, 0, operation, null, null, null,

                null, null);

    }
@@ -542,8 +550,8 @@ public class AlarmManager { 
     * invoked via the specified target Handler, or on the application's main looper

     * if {@code null} is passed as the {@code targetHandler} parameter.

     */

    public void setExact(int type, long triggerAtMillis, String tag, OnAlarmListener listener,

            Handler targetHandler) {

    public void setExact(@AlarmType int type, long triggerAtMillis, String tag,

            OnAlarmListener listener, Handler targetHandler) {

        setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, 0, null, listener, tag,

                targetHandler, null, null);

    }
@@ -553,8 +561,8 @@ public class AlarmManager { 
     * the given time.

     * @hide

     */

    public void setIdleUntil(int type, long triggerAtMillis, String tag, OnAlarmListener listener,

            Handler targetHandler) {

    public void setIdleUntil(@AlarmType int type, long triggerAtMillis, String tag,

            OnAlarmListener listener, Handler targetHandler) {

        setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, FLAG_IDLE_UNTIL, null,

                listener, tag, targetHandler, null, null);

    }
@@ -590,8 +598,8 @@ public class AlarmManager { 


    /** @hide */

    @SystemApi

    public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis,

            PendingIntent operation, WorkSource workSource) {

    public void set(@AlarmType int type, long triggerAtMillis, long windowMillis,

            long intervalMillis, PendingIntent operation, WorkSource workSource) {

        setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, operation, null, null,

                null, workSource, null);

    }
@@ -606,8 +614,9 @@ public class AlarmManager { 
     *

     * @hide

     */

    public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis,

            String tag, OnAlarmListener listener, Handler targetHandler, WorkSource workSource) {

    public void set(@AlarmType int type, long triggerAtMillis, long windowMillis,

            long intervalMillis, String tag, OnAlarmListener listener, Handler targetHandler,

            WorkSource workSource) {

        setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, null, listener, tag,

                targetHandler, workSource, null);

    }
@@ -623,15 +632,17 @@ public class AlarmManager { 
     * @hide

     */

    @SystemApi

    public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis,

            OnAlarmListener listener, Handler targetHandler, WorkSource workSource) {

    public void set(@AlarmType int type, long triggerAtMillis, long windowMillis,

            long intervalMillis, OnAlarmListener listener, Handler targetHandler,

            WorkSource workSource) {

        setImpl(type, triggerAtMillis, windowMillis, intervalMillis, 0, null, listener, null,

                targetHandler, workSource, null);

    }



    private void setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis,

            int flags, PendingIntent operation, final OnAlarmListener listener, String listenerTag,

            Handler targetHandler, WorkSource workSource, AlarmClockInfo alarmClock) {

    private void setImpl(@AlarmType int type, long triggerAtMillis, long windowMillis,

            long intervalMillis, int flags, PendingIntent operation, final OnAlarmListener listener,

            String listenerTag, Handler targetHandler, WorkSource workSource,

            AlarmClockInfo alarmClock) {

        if (triggerAtMillis < 0) {

            /* NOTYET

            if (mAlwaysExact) {
@@ -728,8 +739,7 @@ public class AlarmManager { 
     * assured that it will get similar behavior on both current and older versions

     * of Android.

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should first

     * go off, using the appropriate clock (depending on the alarm type).  This

     * is inexact: the alarm will not fire before this time, but there may be a
@@ -763,7 +773,7 @@ public class AlarmManager { 
     * @see #INTERVAL_HALF_DAY

     * @see #INTERVAL_DAY

     */

    public void setInexactRepeating(int type, long triggerAtMillis,

    public void setInexactRepeating(@AlarmType int type, long triggerAtMillis,

            long intervalMillis, PendingIntent operation) {

        setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, 0, operation, null,

                null, null, null, null);
@@ -795,8 +805,7 @@ public class AlarmManager { 
     * <p>Regardless of the app's target SDK version, this call always allows batching of the

     * alarm.</p>

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should go

     * off, using the appropriate clock (depending on the alarm type).

     * @param operation Action to perform when the alarm goes off;
@@ -814,7 +823,8 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void setAndAllowWhileIdle(int type, long triggerAtMillis, PendingIntent operation) {

    public void setAndAllowWhileIdle(@AlarmType int type, long triggerAtMillis,

            PendingIntent operation) {

        setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, 0, FLAG_ALLOW_WHILE_IDLE,

                operation, null, null, null, null, null);

    }
@@ -848,8 +858,7 @@ public class AlarmManager { 
     * device is idle it may take even more liberties with scheduling in order to optimize

     * for battery life.</p>

     *

     * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},

     *        {@link #RTC}, or {@link #RTC_WAKEUP}.

     * @param type type of alarm.

     * @param triggerAtMillis time in milliseconds that the alarm should go

     *        off, using the appropriate clock (depending on the alarm type).

     * @param operation Action to perform when the alarm goes off;
@@ -868,7 +877,8 @@ public class AlarmManager { 
     * @see #RTC

     * @see #RTC_WAKEUP

     */

    public void setExactAndAllowWhileIdle(int type, long triggerAtMillis, PendingIntent operation) {

    public void setExactAndAllowWhileIdle(@AlarmType int type, long triggerAtMillis,

            PendingIntent operation) {

        setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, FLAG_ALLOW_WHILE_IDLE, operation,

                null, null, null, null, null);

    }

core/java/android/app/Notification.java

+11 −5
Original line number Diff line number Diff line
@@ -676,7 +676,16 @@ public class Notification implements Parcelable 
     * Finally, a notification can be made {@link #VISIBILITY_SECRET}, which will suppress its icon

     * and ticker until the user has bypassed the lockscreen.

     */

    public int visibility;

    public @Visibility int visibility;



    /** @hide */

    @IntDef(prefix = { "VISIBILITY_" }, value = {

            VISIBILITY_PUBLIC,

            VISIBILITY_PRIVATE,

            VISIBILITY_SECRET,

    })

    @Retention(RetentionPolicy.SOURCE)

    public @interface Visibility {}



    /**

     * Notification visibility: Show this notification in its entirety on all lockscreens.
@@ -3545,12 +3554,9 @@ public class Notification implements Parcelable 
        /**

         * Specify the value of {@link #visibility}.

         *

         * @param visibility One of {@link #VISIBILITY_PRIVATE} (the default),

         * {@link #VISIBILITY_SECRET}, or {@link #VISIBILITY_PUBLIC}.

         *

         * @return The same Builder.

         */

        public Builder setVisibility(int visibility) {

        public Builder setVisibility(@Visibility int visibility) {

            mN.visibility = visibility;

            return this;

        }