driver,resource: add docstrings to multiple files

labgrid/driver/bareboxdriver.py

@@ -19,7 +19,12 @@
 @target_factory.reg_driver
 @attr.s
 class BareboxDriver(CommandMixin, Driver, CommandProtocol, LinuxBootProtocol):
-    """BareboxDriver - Driver to control barebox via the console"""
+    """BareboxDriver - Driver to control barebox via the console.
+       BareboxDriver binds on top of a ConsoleProtocol.
+
+    Args:
+        prompt (str): The default Barebox Prompt
+    """
     bindings = {"console": ConsoleProtocol, }
     prompt = attr.ib(default="", validator=attr.validators.instance_of(str))
 
@@ -32,20 +37,31 @@ def __attrs_post_init__(self):
         self._status = 0
 
     def on_activate(self):
+        """Activate the BareboxDriver
+
+        This function checks for a prompt and awaits it if not already active
+        """
         self._check_prompt()
         if self._status == 0:
             self.await_prompt()
 
     def on_deactivate(self):
+        """Deactivate the BareboxDriver
+
+        Simply sets the internal status to 0
+        """
         self._status = 0
 
     @step(args=['cmd'])
-    def run(self, cmd, *, step):
+    def run(self, cmd: str, *, step):
         """
-        Runs the specified cmd on the shell and returns the output.
+        Runs the specified command on the shell and returns the output.
 
-        Arguments:
-        cmd - cmd to run on the shell
+        Args:
+            cmd (str): command to run on the shell
+
+        Returns:
+            Tuple[List[str],List[str], int]: if successful, None otherwise
         """
         # FIXME: Handle pexpect Timeout
         marker = gen_marker()
@@ -71,28 +87,35 @@ def run(self, cmd, *, step):
         else:
             return None
 
-    def run_check(self, cmd):
+    def run_check(self, cmd: str):
         """
-        Runs the specified cmd on the shell and returns the output if successful,
+        Runs the specified command on the shell and returns the output if successful,
         raises ExecutionError otherwise.
 
-        Arguments:
-        cmd - cmd to run on the shell
+        Args:
+            cmd (str): command to run on the shell
+
+        Returns:
+            List[str]: stdout of the executed command
         """
         res = self.run(cmd)
         if res[2] != 0:
             raise ExecutionError(cmd)
         return res[0]
 
     def get_status(self):
-        """Returns the status of the barebox driver.
-        0 means not connected/found, 1 means shell
+        """Retrieve status of the BareboxDriver
+        0 means inactive, 1 means active.
+
+        Returns:
+            int: status of the driver
         """
         return self._status
 
     def _check_prompt(self):
         """
-        Internal function to check if we have a valid prompt
+        Internal function to check if we have a valid prompt.
+        It sets the internal _status to 1 or 0 based on the prompt detection.
         """
         self.console.sendline("")
         try:
@@ -111,9 +134,16 @@ def await_prompt(self):
             self._check_prompt()
 
     def await_boot(self):
+        """Wait for the initial Linux version string to verify we succesfully
+        jumped into the kernel.
+        """
         self.console.expect(r"Linux version \d")
 
-    def boot(self, name):
+    def boot(self, name: str):
+        """Boot the default or a specific boot entry
+
+        Args:
+            name (str): name of the entry to boot"""
         if name:
             self.console.sendline("boot -v {}".format(name))
         else:

labgrid/driver/shelldriver.py

@@ -21,7 +21,16 @@
 @target_factory.reg_driver
 @attr.s
 class ShellDriver(CommandMixin, Driver, CommandProtocol):
-    """ShellDriver - Driver to execute commands on the shell"""
+    """ShellDriver - Driver to execute commands on the shell
+    ShellDriver binds on top of a ConsoleProtocol.
+
+    Args:
+        prompt (regex): The Linux Prompt to detect
+        login_prompt (regex): The Login Prompt to detect
+        username (str): username to login with
+        password (str): password to login with
+        keyfile (str): keyfile to bind mount over users authorized keys
+    """
     bindings = {"console": ConsoleProtocol, }
     prompt = attr.ib(validator=attr.validators.instance_of(str))
     login_prompt = attr.ib(validator=attr.validators.instance_of(str))

labgrid/driver/ubootdriver.py

@@ -18,7 +18,14 @@
 @target_factory.reg_driver
 @attr.s
 class UBootDriver(CommandMixin, Driver, CommandProtocol, LinuxBootProtocol):
-    """UBootDriver - Driver to control uboot via the console"""
+    """UBootDriver - Driver to control uboot via the console.
+    UBootDriver binds on top of a ConsoleProtocol.
+
+    Args:
+        prompt (str): The default UBoot Prompt
+        password (str): optional password to unlock UBoot
+        init_commands (Tuple[str]): a tuple of commands to run after unlock
+    """
     bindings = {"console": ConsoleProtocol, }
     prompt = attr.ib(default="", validator=attr.validators.instance_of(str))
     password = attr.ib(default="", validator=attr.validators.instance_of(str))
@@ -33,19 +40,30 @@ def __attrs_post_init__(self):
         self._status = 0
 
     def on_activate(self):
+        """Activate the UBootDriver
+
+        This function checks for a prompt and awaits it if not already active
+        """
         if self._status == 0:
             self.await_prompt()
 
     def on_deactivate(self):
+        """Deactivate the UBootDriver
+
+        Simply sets the internal status to 0
+        """
         self._status = 0
 
     @step(args=['cmd'], result=True)
     def run(self, cmd):
         """
-        Runs the specified cmd on the shell and returns the output.
+        Runs the specified command on the shell and returns the output.
+
+        Args:
+            cmd (str): command to run on the shell
 
-        Arguments:
-        cmd - cmd to run on the shell
+        Returns:
+            Tuple[List[str],List[str], int]: if successful, None otherwise
         """
         # FIXME: Handle pexpect Timeout
         # TODO: Shell Escaping for the U-Boot Shell
@@ -77,26 +95,33 @@ def run(self, cmd):
     @step(args=['cmd'], result=True)
     def run_check(self, cmd):
         """
-        Runs the specified cmd on the shell and returns the output if successful,
+        Runs the specified command on the shell and returns the output if successful,
         raises ExecutionError otherwise.
 
-        Arguments:
-        cmd - cmd to run on the shell
+        Args:
+            cmd (str): command to run on the shell
+
+        Returns:
+            List[str]: stdout of the executed command
         """
         res = self.run(cmd)
         if res[2] != 0:
             raise ExecutionError(cmd)
         return res[0]
 
     def get_status(self):
-        """Returns the status of the uboot driver.
-        0 means not connected/found, 1 means shell
+        """Retrieve status of the UBootDriver.
+        0 means inactive, 1 means active.
+
+        Returns:
+            int: status of the driver
         """
         return self._status
 
     def _check_prompt(self):
         """
-        Internal function to check if we have a valid prompt
+        Internal function to check if we have a valid prompt.
+        It sets the internal _status to 1 or 0 based on the prompt detection.
         """
         marker = gen_marker()
         # hide marker from expect
@@ -111,7 +136,9 @@ def _check_prompt(self):
 
     @step()
     def await_prompt(self):
-        """Await autoboot line and stop it to get to the prompt"""
+        """Await autoboot line and stop it to get to the prompt, optionally
+        enter the password.
+        """
         self.console.expect(r"U-Boot 20\d+")
         index, _, _, _ = self.console.expect(
             [self.prompt, "stop autoboot", "enter Password:"]
@@ -131,11 +158,17 @@ def await_prompt(self):
 
     @step()
     def await_boot(self):
-        """Wait for boot line of the linux kernel"""
+        """Wait for the initial Linux version string to verify we succesfully
+        jumped into the kernel.
+        """
         self.console.expect(r"Linux version \d")
 
     @step(args=['name'])
     def boot(self, name):
+        """Boot the default or a specific boot entry
+
+        Args:
+            name (str): name of the entry to boot"""
         if name:
             self.console.sendline("boot -v {}".format(name))
         else:

labgrid/resource/base.py

@@ -5,10 +5,19 @@
 
 @attr.s
 class SerialPort(Resource):
+    """The basic SerialPort describes port and speed
+
+    Args:
+        port (str): port to connect to
+        speed (int): speed of the port, defaults to 115200"""
     port = attr.ib(default=None)
     speed = attr.ib(default=115200, validator=attr.validators.instance_of(int))
 
 
 @attr.s
 class EthernetInterface(Resource):
+    """The basic EthernetInterface contains an interfacename
+
+    Args:
+        ifname (str): name of the interface"""
     ifname = attr.ib(default=None)

labgrid/resource/common.py

@@ -13,6 +13,7 @@ class Resource(BindingMixin):
     use.
 
     Life cycle:
+
     - create
     - bind (n times)
     """
@@ -25,6 +26,15 @@ def command_prefix(self):
 
 @attr.s
 class NetworkResource(Resource):
+    """
+    Represents a remote Resource available on another computer.
+
+    This stores a command_prefix to describe how to connect to the remote
+    computer.
+
+    Args:
+        host (str): remote host the resource is available on
+    """
     host = attr.ib(validator=attr.validators.instance_of(str))
 
     @property

labgrid/resource/onewireport.py

@@ -9,8 +9,8 @@
 class OneWirePIO(Resource):
     """This resource describes a Onewire PIO Port.
 
-    Arguments:
-    host - The hostname of the owserver e.g. localhost:4304
-    path - Path to the port on the owserver e.g. 29.7D6913000000/PIO.0"""
+    Args:
+        host (str): hostname of the owserver e.g. localhost:4304
+        path (str): path to the port on the owserver e.g. 29.7D6913000000/PIO.0"""
     host = attr.ib(validator=attr.validators.instance_of(str))
     path = attr.ib(validator=attr.validators.instance_of(str))

labgrid/resource/power.py

@@ -7,6 +7,13 @@
 @target_factory.reg_resource
 @attr.s
 class NetworkPowerPort(Resource):
+    """The NetworkPowerPort describes a remotely switchable PowerPort
+
+    Args:
+        model (str): model of the external power switch
+        host (str): host to connect to
+        index (str): index of the power port on the external switch
+    """
     model = attr.ib(validator=attr.validators.instance_of(str))
     host = attr.ib(validator=attr.validators.instance_of(str))
     index = attr.ib(validator=attr.validators.instance_of(str),

labgrid/resource/serialport.py

@@ -8,6 +8,7 @@
 @target_factory.reg_resource
 @attr.s
 class RawSerialPort(SerialPort, Resource):
+    """RawSerialPort describes a serialport which is vailable on the local computer."""
     def __attrs_post_init__(self):
         super().__attrs_post_init__()
         if self.port is None:
@@ -17,5 +18,11 @@ def __attrs_post_init__(self):
 @target_factory.reg_resource
 @attr.s
 class NetworkSerialPort(NetworkResource):
+    """A NetworkSerialPort is a remotely accessable serialport, usually
+    accessed via rfc2217.
+
+    Args:
+        port (str): connection string to the port e.g. 'rfc2217://<host>:<port>'
+        speed (int): speed of the port e.g. 9800"""
     port = attr.ib(validator=attr.validators.instance_of(int))
     speed = attr.ib(default=115200, validator=attr.validators.instance_of(int))