libkirk: fix all wrong docstrings

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>

Author: acerv

libkirk/channels/ltx.py

@@ -23,7 +23,7 @@
 
 class Request:
     """
-    LTX request.
+    LTX client request.
     """
 
     ERROR = 0xFF
@@ -51,14 +51,16 @@ def __init__(self) -> None:
     @property
     def completed(self) -> bool:
         """
-        If True the request has been completed.
+        :return: True if request has been completed. False otherwise.
+        :rtype: bool
         """
         return self._completed
 
     def add_done_coro(self, coro: Callable) -> None:
         """
         Add done event to request.
-        :param coro: called when request is done
+
+        :param coro: Called when request is completed.
         :type coro: Callable
         """
         self._done_coro.append(coro)
@@ -78,14 +80,18 @@ async def _raise_complete(self, *args: Any) -> None:
     async def pack(self) -> bytes:
         """
         Pack LTX request into bytes.
+
+        :return: Request bytes.
+        :rtype: bytes
         """
         raise NotImplementedError()
 
     async def feed(self, message: List[Any]) -> None:
         """
         Feed request queue with data and return when the request
         has been completed.
-        :param message: processed msgpack message
+
+        :param message: Processed msgpack message.
         :type message: list
         """
         raise NotImplementedError()
@@ -158,12 +164,12 @@ class env(Request):
 
         def __init__(self, slot_id: int, key: str, value: str) -> None:
             """
-            :param slot_id: command table ID. Can be None if we want to apply
-                the same environment variable to all executions
+            :param slot_id: Command table ID. Can be None if we want to apply
+                the same environment variable to all executions.
             :type slot_id: int
-            :param key: key of the environment variable
+            :param key: Key of the environment variable.
             :type key: str
-            :param value: value of the environment variable
+            :param value: Value of the environment variable.
             :type value: str
             """
             super().__init__()
@@ -207,10 +213,10 @@ class cwd(Request):
 
         def __init__(self, slot_id: int, path: str) -> None:
             """
-            :param slot_id: command table ID. Can be None if we want to apply
+            :param slot_id: Command table ID. Can be None if we want to apply
                 the same current working directory to all executions
             :type slot_id: int
-            :param path: current working path
+            :param path: Current working path.
             :type path: str
             """
             super().__init__()
@@ -256,7 +262,7 @@ class get_file(Request):
 
         def __init__(self, path: str) -> None:
             """
-            :param path: path of the file to read
+            :param path: Path of the file to read.
             :type path: str
             """
             super().__init__()
@@ -471,22 +477,24 @@ class LTX:
     """
     This class communicates with LTX by processing given requests.
     Typical usage is the following:
-    ```
-    async with LTX(infile, outfile) as ltx:
-        # create requests
-        request1 = Requests.execute("echo 'hello world' > myfile")
-        request2 = Requests.get_file("myfile")
-
-        # set the complete event
-        request1.add_done_coro(exec_complete_handler)
-        request2.add_done_coro(get_file_complete_handler)
-
-        # send request
-        ltx.send([request1, request2])
-
-        # process events output
-        ...
-    ```
+
+    .. code-block:: python
+
+        async with LTX(infile, outfile) as ltx:
+            # create requests
+            request1 = Requests.execute("echo 'hello world' > myfile")
+            request2 = Requests.get_file("myfile")
+
+            # set the complete event
+            request1.add_done_coro(exec_complete_handler)
+            request2.add_done_coro(get_file_complete_handler)
+
+            # send request
+            ltx.send([request1, request2])
+
+            # process events output
+            ...
+
     """
 
     BUFFSIZE = 1 << 21
@@ -575,7 +583,8 @@ async def send(self, requests: List[Request]) -> None:
         """
         Send requests to LTX service. The order is preserved during
         requests execution.
-        :param requests: list of requests to send
+
+        :param requests: List of requests to send.
         :type requests: list
         """
         if not requests:
@@ -599,6 +608,12 @@ async def gather(self, requests: List[Request]) -> Dict[Request, Any]:
         Gather multiple requests and wait for the response, then return all
         rquests' replies inside a dictionary that maps requests with their
         reply.
+
+        :param requests: List of requests to process.
+        :type requests: list(Request)
+        :return: Dictionary containing Request as keys and data from completed
+            requests as values.
+        :rtype: dict
         """
         req_len = len(requests)
         replies = {}

libkirk/com.py

@@ -18,12 +18,15 @@
 
 class IOBuffer:
     """
-    IO stdout buffer. The API is similar to ``IO`` types.
+    IO stdout buffer. The API is similar to IO types.
     """
 
     async def write(self, data: str) -> None:
         """
-        Write ``data`` inside the buffer.
+        Write data inside the buffer.
+
+        :param data: Data to write.
+        :type data: str
         """
         raise NotImplementedError()
 
@@ -38,22 +41,24 @@ class ComChannel(Plugin):
     @property
     def parallel_execution(self) -> bool:
         """
-        If True, communication supports commands parallel execution.
+        :return: If True, communication supports commands parallel execution.
+        :rtype: bool
         """
         raise NotImplementedError()
 
     @property
     async def active(self) -> bool:
         """
-        Return True if communication is active. False otherwise.
+        :return: Return True if communication is active. False otherwise.
+        :rtype: bool
         """
         raise NotImplementedError()
 
     async def communicate(self, iobuffer: Optional[IOBuffer] = None) -> None:
         """
         Start communication.
 
-        :param iobuffer: buffer used to write stdout
+        :param iobuffer: Buffer used to write stdout.
         :type iobuffer: IOBuffer
         """
         raise NotImplementedError()
@@ -62,15 +67,17 @@ async def stop(self, iobuffer: Optional[IOBuffer] = None) -> None:
         """
         Stop communication.
 
-        :param iobuffer: buffer used to write stdout
+        :param iobuffer: Buffer used to write stdout.
         :type iobuffer: IOBuffer
         """
         raise NotImplementedError()
 
     async def ping(self) -> float:
         """
         Send a ping request and verify how much reply takes in seconds.
-        :returns: float
+
+        :return: Time between ping and pong.
+        :rtype: float
         """
         raise NotImplementedError()
 
@@ -84,48 +91,52 @@ async def run_command(
         """
         Run a command.
 
-        :param command: command to execute
+        :param command: Command to execute.
         :type command: str
-        :param cwd: current working directory
+        :param cwd: Current working directory.
         :type cwd: str
-        :param env: environment variables
+        :param env: Environment variables.
         :type env: dict
-        :param iobuffer: buffer used to write stdout
+        :param iobuffer: Buffer used to write stdout.
         :type iobuffer: IOBuffer
-        :returns: dictionary containing command execution information
+        :return: Dictionary containing information about the executed command.
+
+            .. code-block:: python
 
-            {
-                "command": <str>,
-                "returncode": <int>,
-                "stdout": <str>,
-                "exec_time": <float>,
-            }
+                {
+                    "command": <str>,
+                    "returncode": <int>,
+                    "stdout": <str>,
+                    "exec_time": <float>,
+                }
 
-            If None is returned, then callback failed.
+            If None is returned, then callback has failed.
+        :rtype: dict
         """
         raise NotImplementedError()
 
     async def fetch_file(self, target_path: str) -> bytes:
         """
         Fetch file and return its content.
 
-        :param target_path: path of the file to download from target
+        :param target_path: Path of the file to download from target.
         :type target_path: str
-        :returns: bytes contained in target_path
+        :return: Data contained in target_path.
+        :rtype: bytes
         """
         raise NotImplementedError()
 
     async def ensure_communicate(
         self, iobuffer: Optional[IOBuffer] = None, retries: int = 10
     ) -> None:
         """
-        Ensure that ``communicate`` is completed, retrying as many times we
-        want in case of ``KirkException`` error. After each error, the
+        Ensure that communicate is completed, retrying as many times we
+        want in case of KirkException error. After each error, the
         communication is stopped and a new communication is performed.
 
-        :param iobuffer: buffer used to write stdout
+        :param iobuffer: Buffer used to write stdout.
         :type iobuffer: IOBuffer
-        :param retries: number of times we retry to communicate
+        :param retries: Number of times we retry to communicate.
         :type retries: int
         """
         retries = max(retries, 1)
@@ -144,11 +155,13 @@ async def ensure_communicate(
 def discover(path: str, extend: bool = True) -> None:
     """
     Discover all ComChannel implementations inside `path`.
-    :param path: directory where searching for channel implementations
+
+    :param path: Directory where searching for channel implementations.
     :type path: str
-    :param extend: if True, it will add new discovered channels on top of the
+    :param extend: If True, it will add new discovered channels on top of the
         ones already found. If False, previous discovered channels will be
         cleared.
+    :rtype: bool
     """
     global _COM
 
@@ -161,7 +174,8 @@ def discover(path: str, extend: bool = True) -> None:
 
 def get_channels() -> List[ComChannel]:
     """
-    :return: list of loaded ComChannel implementations.
+    :return: List of loaded ComChannel implementations.
+    :rtype: list(ComChannel)
     """
     global _COM
     # pyrefly: ignore[bad-return]
@@ -170,14 +184,16 @@ def get_channels() -> List[ComChannel]:
 
 def clone_channel(name: str, new_name: str) -> Plugin:
     """
-    Clone a channel implementation named ``name`` and rename it with
-    ``new_name``. The new plugin will be registered with the other
+    Clone a channel implementation named name and rename it with
+    new_name. The new plugin will be registered with the other
     plugins.
-    :param name: plugin name
+
+    :param name: Plugin name.
     :type name: str
-    :param new_name: new cloned plugin name
+    :param new_name: New cloned plugin name.
     :type new_name: str
-    :return: new plugin object
+    :return: New plugin object.
+    :rtype: Plugin
     """
     global _COM