From ad77d95081e008892b11a785e03aef2d3bb8c27c Mon Sep 17 00:00:00 2001
From: William Hobbs <13199119+wihobbs@users.noreply.github.com>
Date: Thu, 12 Oct 2023 21:08:19 +0000
Subject: [PATCH] python: add flux.job.list docstrings

Problem: Missing docstrings in some flux.job.list functions.

Solution: Add them.
---
 src/bindings/python/flux/job/list.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/bindings/python/flux/job/list.py b/src/bindings/python/flux/job/list.py
index 10cca0ca7dae..0b2f8faad84f 100644
--- a/src/bindings/python/flux/job/list.py
+++ b/src/bindings/python/flux/job/list.py
@@ -20,9 +20,13 @@
 
 class JobListRPC(RPC):
     def get_jobs(self):
+        """Returns all jobs in the RPC"""
         return self.get()["jobs"]
 
     def get_jobinfos(self):
+        """Yields a JobInfo object for each job in its current state
+
+        :rtype: JobInfo"""
         for job in self.get_jobs():
             yield JobInfo(job)
 
@@ -75,6 +79,9 @@ def job_list(
 def job_list_inactive(
     flux_handle, since=0.0, max_entries=1000, attrs=["all"], name=None, queue=None
 ):
+    """
+    List only inactive jobs
+    """
     return job_list(
         flux_handle,
         max_entries=max_entries,
@@ -96,12 +103,22 @@ def get_job(self):
         return self.get()["job"]
 
     def get_jobinfo(self):
+        """
+        Returns a JobInfo object for the job.
+        """
         return JobInfo(self.get_job())
 
 
 # list-id is not like list or list-inactive, it doesn't return an
 # array, so don't use JobListRPC
 def job_list_id(flux_handle, jobid, attrs=["all"]):
+    """Watch a job by providing an ID.
+
+    This is a non-blocking function that allows users to asynchronously
+    get job event data. Returns a RPC future that is fulfilled each time
+    the job enters a new state.
+    :rtype: JobListIdRPC
+    """
     payload = {"id": int(jobid), "attrs": attrs}
     rpc = JobListIdRPC(flux_handle, "job-list.list-id", payload)
     #  save original JobId argument for error reporting