docstrings are really tedious

src/lsst/cmservice/db/dbid.py

@@ -9,8 +9,8 @@
 class DbId:
     """Information to identify a single entry in the CM database tables"""
 
-    _level: LevelEnum
-    _id: int
+    _level: LevelEnum  # Which table
+    _id: int  # Primary key in that table
 
     def __repr__(self) -> str:
         return f"DbId({self._level.name}:{self._id})"

src/lsst/cmservice/db/dependency.py

@@ -16,8 +16,8 @@
 class StepDependency(Base, RowMixin):
     """Database table to establish dependecy of one step on another
 
-    A StepDependency will prevent the `depend_id` entry
-    from running until the `prereq` entry is accepted
+    A StepDependency will prevent the `depend_` entry
+    from running until the `prereq_` entry is accepted
     """
 
     __tablename__ = "step_dependency"
@@ -44,6 +44,18 @@ async def is_done(
         self,
         session: async_scoped_session,
     ) -> bool:
+        """Check if this dependency is completed
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        Returns
+        -------
+        done: bool
+            Returns True if the prerequisite is done
+        """
         prereq = await Step.get_row(session, self.prereq_id)
         if prereq.status.value >= StatusEnum.accepted.value:
             return True
@@ -53,8 +65,8 @@ async def is_done(
 class ScriptDependency(Base, RowMixin):
     """Database table to establish dependecy of one script on another
 
-    A StepDependency will prevent the `depend_id` entry
-    from running until the `prereq` entry is accepted
+    A ScriptDependency will prevent the `depend_` entry
+    from running until the `prereq_` entry is accepted
     """
 
     __tablename__ = "script_dependency"
@@ -73,6 +85,18 @@ async def is_done(
         self,
         session: async_scoped_session,
     ) -> bool:
+        """Check if this dependency is completed
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        Returns
+        -------
+        done: bool
+            Returns True if the prerequisite is done
+        """
         prereq = await Script.get_row(session, self.prereq_id)
         if prereq.status.value >= StatusEnum.accepted.value:
             return True

src/lsst/cmservice/db/element_handler.py

@@ -25,6 +25,24 @@ async def add_prerequisite(
         script_id: int,
         prereq_id: int,
     ) -> ScriptDependency:
+        """Add a prerequite to running a `Script`
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+            
+        script_id: int
+            Id for the script that depends on the other
+
+        prereq_id: int,
+            Id for the script that is a prerequisite for the other
+
+        Returns
+        -------
+        new_depend : ScriptDependency
+            Newly created dependency
+        """
         new_depend = await ScriptDependency.create_row(
             session,
             prereq_id=prereq_id,
@@ -41,7 +59,24 @@ async def process(
         element: ElementMixin,
         **kwargs: Any,
     ) -> StatusEnum:
-        """Process this element as much as possible"""
+        """Process a `Element` as much as possible
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        kwargs: Any
+            Used to override processing configuration
+
+        Returns
+        -------
+        status : StatusEnum
+            The status of the processing
+        """
         status = element.status
         if status == StatusEnum.waiting:
             is_ready = await element.check_prequisites(session, element)
@@ -64,6 +99,24 @@ async def prepare(
         session: async_scoped_session,
         element: ElementMixin,
     ) -> StatusEnum:
+        """Prepare `Element` for processing
+
+        This means creating database entries for scripts and 
+        dependencies between them
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        Returns
+        -------
+        status : StatusEnum
+            The status of the processing
+        """
         element_class = type(element)
         query = (
             select(element_class)
@@ -114,6 +167,23 @@ async def continue_processing(
         session: async_scoped_session,
         element: ElementMixin,
     ) -> StatusEnum:
+        """Continue `Element` processing
+
+        This means processing the scripts associated to this element
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        Returns
+        -------
+        status : StatusEnum
+            The status of the processing
+        """
         scripts = await element.get_scripts(session, element, remaining_only=True)
         if scripts:
             for script_ in scripts:
@@ -128,6 +198,21 @@ async def run_script_checks(
         element: ElementMixin,
         **kwargs: Any,
     ) -> None:
+        """Explicitly check on Scripts associated to this Element
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        Keywords
+        --------
+        force_check : bool
+            If True check all scripts, not only remaining ones
+        """
         scripts = await element.get_scripts(
             session, element, remaining_only=not kwargs.get("force_check", False)
         )
@@ -140,6 +225,21 @@ async def run_job_checks(
         element: ElementMixin,
         **kwargs: Any,
     ) -> None:
+        """Explicitly check on Jobs associated to this Element
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        Keywords
+        --------
+        force_check : bool
+            If True check all jobs, not only remaining ones
+        """
         jobs = await element.get_jobs(session, element, remaining_only=not kwargs.get("force_check", False))
         for job_ in jobs:
             await job_.run_check(session, job_.group_)
@@ -150,6 +250,25 @@ async def update_status(
         element: ElementMixin,
         **kwargs: Any,
     ) -> StatusEnum:
+        """Update the status of this Element based on the 
+        status of the associated scripts and jobs
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        element: ElementMixin
+            `Element` in question
+
+        Keywords
+        --------
+        do_checks: bool
+            If True, explicitly run checks on status of jobs and scripts
+
+        force_check : bool
+            If True check all jobs and scripts, not only remaining ones
+        """
         if kwargs.get("do_checks", False):
             await self.run_script_checks(session, element, **kwargs)
             await self.run_job_checks(session, element, **kwargs)

src/lsst/cmservice/db/job.py

@@ -81,7 +81,24 @@ async def process(
         session: async_scoped_session,
         parent: Group,
     ) -> StatusEnum:
-        """Process this element as much as possible"""
+        """Process this `Job` as much as possible
+
+        This will create a `JobHandler` and
+        pass this job to it for processing
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        parent: Group
+            Parent Element of the `Job` in question
+
+        Returns
+        -------
+        status : StatusEnum
+            The status of the processing
+        """
         handler = await self.get_handler(session, self)
         assert isinstance(handler, JobHandler)
         status = await handler.process(session, self, parent)
@@ -92,7 +109,24 @@ async def run_check(
         session: async_scoped_session,
         parent: Group,
     ) -> StatusEnum:
-        """Process this element as much as possible"""
+        """Check on the status of this `Job`
+
+        This will create a `JobHandler` and
+        pass this `Job` to it for processing
+
+        Parameters
+        ----------
+        session : async_scoped_session
+            DB session manager
+
+        parent: Group
+            Parent Element of the `Job` in question
+
+        Returns
+        -------
+        status : StatusEnum
+            The status of the processing
+        """
         handler = await self.get_handler(session, self)
         assert isinstance(handler, JobHandler)
         status = await handler.check(session, self, parent)