jobqueue: expand architecture documentation

Why:

- The JobQueue docs currently do not describe the
  semantics of handling job execution failures.
- Some other features, such as job deduplication, enqueue semantics and
  the overall execution flow, are also missing from the architecture
  document.

What:

- Expand the JobQueue architecture document to describe how jobs that
  return false from Job::run() or complete exceptionally are treated.
- Rework some preexisting sections of the same document for brevity.
- Describe JobSpecification and JobQueueGroup in the same document.
- Describe the different between push() and lazyPush() semantics.
- Describe the execution flow of a Job.
- Briefly summarize how job deduplication is expected to function.

Change-Id: Ib0c1f165feabefe862710b28977b598faf637ec5

1 files changed, 1 insertions, 4 deletions

diff --git a/includes/jobqueue/Job.php b/includes/jobqueue/Job.php
index 2bbec7491e4b..d6a909ed4319 100644
--- a/includes/jobqueue/Job.php
+++ b/includes/jobqueue/Job.php
@@ -27,10 +27,7 @@ use MediaWiki\Title\Title;
 /**
  * Describe and execute a background job.
  *
- * Push jobs onto queues via the JobQueueGroup service.
- *
- * Job objects must implement IJobSpecification to allow JobQueue to store the job,
- * and later re-constructing the object from storage in a JobRunner.
+ * Callers should use JobQueueGroup to enqueue jobs for deferred execution.
  *
  * See [the architecture doc](@ref jobqueuearch) for more information.
  *