Added docstrings to V2 methods in the CallbackBase Class (4 & 5 of 27) (#83507)

* Added docstrings to V2 methods in the CallbackBase Class (4 & 5 of 27)

* Made corrections as requested by webknjaz.

* Cleaned up whitespace issues.

* Corrections to customization note for review by webknjaz.

* Added rtype to return in docstrings.

* Simplified docstrings.


Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Sviatoslav Sydorenko <webknjaz@redhat.com>

1 files changed, 51 insertions, 27 deletions

diff --git a/lib/ansible/plugins/callback/__init__.py b/lib/ansible/plugins/callback/__init__.py
index c88fbd5572..aa75ac5fa3 100644
--- a/lib/ansible/plugins/callback/__init__.py
+++ b/lib/ansible/plugins/callback/__init__.py
@@ -506,67 +506,91 @@ class CallbackBase(AnsiblePlugin):
         self.on_any(args, kwargs)
 
     def v2_runner_on_failed(self, result: TaskResult, ignore_errors: bool = False) -> None:
-        """Get details about a failed task and whether or not Ansible should continue
-        running tasks on the host where the failure occurred, then process the details
-        as required by the callback (output, profiling, logging, notifications, etc.)
+        """Process results of a failed task.
 
-        Note: The 'ignore_errors' directive only works when the task can run and returns
-        a value of 'failed'. It does not make Ansible ignore undefined variable errors,
-        connection failures, execution issues (for example, missing packages), or syntax errors.
+        Note: The value of 'ignore_errors' tells Ansible whether to
+        continue running tasks on the host where this task failed.
+        But the 'ignore_errors' directive only works when the task can
+        run and returns a value of 'failed'. It does not make Ansible
+        ignore undefined variable errors, connection failures, execution
+        issues (for example, missing packages), or syntax errors.
 
-        Customization note: For more information about the attributes and methods of the
-        TaskResult class, see lib/ansible/executor/task_result.py.
-
-        :param TaskResult result: An object that contains details about the task
-        :param bool ignore_errors: Whether or not Ansible should continue running tasks on the host
-        where the failure occurred
+        :param result: The parameters of the task and its results.
+        :type result: TaskResult
+        :param ignore_errors: Whether Ansible should continue \
+            running tasks on the host where the task failed.
+        :type ignore_errors: bool
 
         :return: None
+        :rtype: None
         """
         host = result._host.get_name()
         self.runner_on_failed(host, result._result, ignore_errors)
 
     def v2_runner_on_ok(self, result: TaskResult) -> None:
-        """Get details about a successful task and process them as required by the callback
-        (output, profiling, logging, notifications, etc.)
-
-        Customization note: For more information about the attributes and methods of the
-        TaskResult class, see lib/ansible/executor/task_result.py.
+        """Process results of a successful task.
 
-        :param TaskResult result: An object that contains details about the task
+        :param result: The parameters of the task and its results.
+        :type result: TaskResult
 
         :return: None
+        :rtype: None
         """
         host = result._host.get_name()
         self.runner_on_ok(host, result._result)
 
     def v2_runner_on_skipped(self, result: TaskResult) -> None:
-        """Get details about a skipped task and process them as required by the callback
-        (output, profiling, logging, notifications, etc.)
+        """Process results of a skipped task.
 
-        Customization note: For more information about the attributes and methods of the
-        TaskResult class, see lib/ansible/executor/task_result.py.
-
-        :param TaskResult result: An object that contains details about the task
+        :param result: The parameters of the task and its results.
+        :type result: TaskResult
 
         :return: None
+        :rtype: None
         """
         if C.DISPLAY_SKIPPED_HOSTS:
             host = result._host.get_name()
             self.runner_on_skipped(host, self._get_item_label(getattr(result._result, 'results', {})))
 
-    def v2_runner_on_unreachable(self, result):
+    def v2_runner_on_unreachable(self, result: TaskResult) -> None:
+        """Process results of a task if a target node is unreachable.
+
+        :param result: The parameters of the task and its results.
+        :type result: TaskResult
+
+        :return: None
+        :rtype: None
+        """
         host = result._host.get_name()
         self.runner_on_unreachable(host, result._result)
 
-    def v2_runner_on_async_poll(self, result):
+    def v2_runner_on_async_poll(self, result: TaskResult) -> None:
+        """Get details about an unfinished task running in async mode.
+
+        Note: The value of the `poll` keyword in the task determines
+        the interval at which polling occurs and this method is run.
+
+        :param result: The parameters of the task and its status.
+        :type result: TaskResult
+
+        :rtype: None
+        :rtype: None
+        """
         host = result._host.get_name()
         jid = result._result.get('ansible_job_id')
         # FIXME, get real clock
         clock = 0
         self.runner_on_async_poll(host, result._result, jid, clock)
 
-    def v2_runner_on_async_ok(self, result):
+    def v2_runner_on_async_ok(self, result: TaskResult) -> None:
+        """Process results of a successful task that ran in async mode.
+
+        :param result: The parameters of the task and its results.
+        :type result: TaskResult
+
+        :return: None
+        :rtype: None
+        """
         host = result._host.get_name()
         jid = result._result.get('ansible_job_id')
         self.runner_on_async_ok(host, result._result, jid)