Expand JS documentation.
1. Make it clear that "minimum latency" != "run ASAP after latency"
2. Note that deadline constraints are dropped from rescheduled jobs
3. Clarify that jobFinished does not need to be called if onStopJob is called
Bug: 19536175
Test: Run `m offline-sdk-docs` and check site at out/target/common/docs/offline-sdk/reference/android/app/job/JobInfo.html
Change-Id: I051feb0ebfcb0a24c452a38b91a751bbeef581f8
diff --git a/apex/jobscheduler/framework/java/android/app/job/JobInfo.java b/apex/jobscheduler/framework/java/android/app/job/JobInfo.java
index 17682a5..52442a6 100644
--- a/apex/jobscheduler/framework/java/android/app/job/JobInfo.java
+++ b/apex/jobscheduler/framework/java/android/app/job/JobInfo.java
@@ -1433,7 +1433,10 @@
}
/**
- * 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 @@
/**
* 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 @@
* 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
diff --git a/apex/jobscheduler/framework/java/android/app/job/JobService.java b/apex/jobscheduler/framework/java/android/app/job/JobService.java
index fa7a2d3..c251529a 100644
--- a/apex/jobscheduler/framework/java/android/app/job/JobService.java
+++ b/apex/jobscheduler/framework/java/android/app/job/JobService.java
@@ -153,6 +153,10 @@
* 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.