minor cleanup in job-manager journal and job-list (mostly inline docs)

src/modules/job-list/job_state.c

@@ -982,11 +982,9 @@ static int journal_process_event (struct job_state_ctx *jsctx,
             return -1;
     }
     else if (streq (name, "flux-restart")) {
-        /* Presently, job-list depends on job-manager.events-journal
-         * service.  So if job-manager reloads, job-list must be
-         * reloaded, making the probability of reaching this
-         * `flux-restart` path very low.  Code added for completeness
-         * and in case dependency removed in the future.
+        /* This can only be seen while processing the journal backlog
+         * as it is posted by the job manager during its KVS restart,
+         * which happens synchronously before the journal RPC is processed.
          */
         if (journal_revert_job (jsctx,
                                 job,

src/modules/job-manager/event.h

@@ -22,9 +22,6 @@ enum job_manager_event_flags {
 
     /*  EVENT_NO_COMMIT events are the same as any other event, except
      *   that the event is not posted to the job eventlog in the KVS.
-     *   The event is not given a global sequence number, since this would
-     *   cause the events to be numbered incorrectly when replayed from
-     *   the eventlog in the KVS.
      */
     EVENT_NO_COMMIT = 1,
 };

src/modules/job-manager/journal.c

@@ -8,7 +8,36 @@
  * SPDX-License-Identifier: LGPL-3.0
 \************************************************************/
 
-/* journal.c - job event journaling and streaming to listeners
+/* journal.c - stream job events
+ *
+ * This allows another service to track detailed information about
+ * all jobs.  The journal consumer makes a job-manger.events-journal
+ * request with optional allow/deny filter and boolean 'full' flag:
+ *   {"full"?b, "allow"?{"name":1, ...}, "deny"?{"name:1, ...}}
+ *
+ * If "full" is true, the journal begins with all the inactive jobs.
+ * If "full" is false, the journal begins with all the active jobs.
+ * If "full" is unspecified, it is assumed to be false.
+ * If allow/deny rules are specified, they filter the job events by name.
+ *
+ * The journal consumer receives a stream of responses until the job
+ * manager is unloaded or the request is canceled.  Each response consists of
+ * an object containing a jobid, an array of events, and optional data:
+ *   {"id":I, "events":[], "jobspec"?s, "R"?s}
+ *
+ * During processing of the initial backlog, the events array will contain
+ * all the events posted so far for each job, plus R and jobspec if available.
+ * The jobs are returned in hash traversal order.  Once backlog processing
+ * is complete, a sentinel response is transmitted with id of FLUX_JOBID_ANY
+ * and an empty events array:
+ *   {"id":-1, "events":[]}
+ *
+ * The sentinel informs the consumer that it is now caught up and that future
+ * responses will be for events that are are posted in real time.
+ *
+ * Additional responses contain at most one event.  The redacted jobspec is
+ * included with the "validate" event.  The redacted R object is included
+ * with the "alloc" event.
  */
 
 #if HAVE_CONFIG_H
@@ -29,8 +58,6 @@
 #include "job.h"
 #include "journal.h"
 
-#define DEFAULT_JOURNAL_SIZE_LIMIT 1000
-
 struct journal {
     struct job_manager *ctx;
     flux_msg_handler_t **handlers;

src/modules/job-manager/prioritize.c

@@ -98,7 +98,7 @@ static int reprioritize_one (struct job_manager *ctx,
         && job->state != FLUX_JOB_STATE_PRIORITY
         && job->priority != FLUX_JOB_PRIORITY_MIN
         && job->priority != FLUX_JOB_PRIORITY_MAX)
-        flags = EVENT_JOURNAL_ONLY;
+        flags = EVENT_NO_COMMIT;
      */
 
     /*  Post 'priority' event.