Merge "Expand JS documentation." into sc-dev

apex/jobscheduler/framework/java/android/app/job/JobInfo.java

@@ -1433,7 +1433,10 @@ public class JobInfo implements Parcelable {
         }
 
         /**
-         * Specify that this job should be delayed by the provided amount of time.
+         * Specify that this job should be delayed by the provided amount of time. The job may not
+         * run the instant the delay has elapsed. JobScheduler will start the job at an
+         * indeterminate time after the delay has elapsed.
+         * <p>
          * Because it doesn't make sense setting this property on a periodic job, doing so will
          * throw an {@link java.lang.IllegalArgumentException} when
          * {@link android.app.job.JobInfo.Builder#build()} is called.
@@ -1449,9 +1452,11 @@ public class JobInfo implements Parcelable {
 
         /**
          * Set deadline which is the maximum scheduling latency. The job will be run by this
-         * deadline even if other requirements are not met. Because it doesn't make sense setting
-         * this property on a periodic job, doing so will throw an
-         * {@link java.lang.IllegalArgumentException} when
+         * deadline even if other requirements (including a delay set through
+         * {@link #setMinimumLatency(long)}) are not met.
+         * <p>
+         * Because it doesn't make sense setting this property on a periodic job, doing so will
+         * throw an {@link java.lang.IllegalArgumentException} when
          * {@link android.app.job.JobInfo.Builder#build()} is called.
          * @see JobInfo#getMaxExecutionDelayMillis()
          */
@@ -1465,6 +1470,7 @@ public class JobInfo implements Parcelable {
          * Set up the back-off/retry policy.
          * This defaults to some respectable values: {30 seconds, Exponential}. We cap back-off at
          * 5hrs.
+         * <p>
          * Note that trying to set a backoff criteria for a job with
          * {@link #setRequiresDeviceIdle(boolean)} will throw an exception when you call build().
          * This is because back-off typically does not make sense for these types of jobs. See

apex/jobscheduler/framework/java/android/app/job/JobService.java

@@ -153,6 +153,10 @@ public abstract class JobService extends Service {
      * Once this method returns (or times out), the system releases the wakelock that it is holding
      * on behalf of the job.</p>
      *
+     * <p class="caution"><strong>Note:</strong> When a job is stopped and rescheduled via this
+     * method call, the deadline constraint is excluded from the rescheduled job's constraint set.
+     * The rescheduled job will run again once all remaining constraints are satisfied.
+     *
      * @param params The parameters identifying this job, similar to what was supplied to the job in
      *               the {@link #onStartJob(JobParameters)} callback, but with the stop reason
      *               included.