Expanding docstrings for reporters (#2904)

Expanding docstrings for reporters

Additional documentation for methods of reporters.

Reviewed-by: gemini-code-assist[bot]
Reviewed-by: Laura Barcziová

Author: softwarefactory-project-zuul[bot]

packit_service/worker/reporting/reporters/base.py

@@ -53,6 +53,8 @@ def get_instance(
     ) -> "StatusReporter":
         """
         Get the StatusReporter instance.
+        The `project` determines type of the reporter returned. All other
+        parameters are passed to the initializer of the chosen reporter.
         """
         from .github import StatusReporterGithubChecks
         from .gitlab import StatusReporterGitlab
@@ -105,6 +107,7 @@ def set_status(
         markdown_content: Optional[str] = None,
         target_branch: Optional[str] = None,
     ):
+        """Set status of the check."""
         raise NotImplementedError()
 
     def report(
@@ -130,7 +133,7 @@ def report(
                 e.g. `{"Testing Farm": "url-to-testing-farm"}`
 
                 Defaults to None
-            check_names: Those in bold.
+            check_names: List of check names
 
                 Defaults to None
             markdown_content: In GitHub checks, we can provide a markdown content.

packit_service/worker/reporting/reporters/github.py

@@ -100,6 +100,13 @@ def set_status(
         markdown_content: Optional[str] = None,
         target_branch: Optional[str] = None,
     ):
+        """
+        Set status of a Github check.
+
+        When encountering `GithubAPIException` falls back to setting
+        Github status directly.
+        """
+
         markdown_content = markdown_content or ""
         state_to_set = self.get_check_run(state)
         logger.debug(

packit_service/worker/reporting/reporters/gitlab.py

@@ -33,6 +33,14 @@ def set_status(
         markdown_content: Optional[str] = None,
         target_branch: Optional[str] = None,
     ):
+        """
+        Set status of a Gitlab check.
+
+        Discards `markdown_content`, as it isn't supported by Gitlab.
+        If attempt to set status of a commit fails with `GitlabAPIException`
+        and error code 400, 403 or 404, it attempts to add a comment instead.
+        """
+
         state_to_set = self.get_commit_status(state)
         logger.debug(
             f"Setting Gitlab status '{state_to_set.name}' for check '{check_name}': {description}",

packit_service/worker/reporting/reporters/pagure.py

@@ -34,6 +34,15 @@ def set_status(
         markdown_content: Optional[str] = None,
         target_branch: Optional[str] = None,
     ):
+        """
+        Set status of a Pagure check.
+
+        If used for a pull request, the UID is derived from SHA256
+        of `check_name` or combination of `check_name` and `target_branch`.
+
+        Value of `url` defaults to `CONTACTS_URL`, since Pagure requires
+        some URL to be submitted.
+        """
         state_to_set = self.get_commit_status(state)
         logger.debug(
             f"Setting Pagure status '{state_to_set.name}' for check '{check_name}' and "