Refactoring and pydoc comments

colcon_cargo/argcomplete_completer/cargo_args.py

@@ -20,7 +20,25 @@ def __init__(self):  # noqa: D107
             ArgcompleteCompleterExtensionPoint.EXTENSION_POINT_VERSION, '^1.0')
 
     def get_completer(self, parser, *args, **kwargs):  # noqa: D102
-        if '--cargo-args' not in args:
+        """
+        Get the completer for Cargo arguments.
+
+        This method checks if the '--cargo-args' argument is present in the provided arguments.
+        If it is, it tries to import the ChoicesCompleter from the argcomplete package and returns
+        an instance of it with an empty list of choices. If the '--cargo-args' argument is not
+        present or the argcomplete package is not installed, it returns None.
+
+        Args:
+            parser: The argument parser.
+            *args: Positional arguments passed to the method.
+            **kwargs: Keyword arguments passed to the method.
+
+        Returns:
+            ChoicesCompleter or None: An instance of ChoicesCompleter with an empty list of choices,
+            or None if the '--cargo-args' argument is not present or the argcomplete package is not
+            installed.
+        """
+        if "--cargo-args" not in args:
             return None
 
         try:

colcon_cargo/package_identification/cargo.py

@@ -15,6 +15,12 @@ class CargoPackageIdentification(PackageIdentificationExtensionPoint):
     """Identify Cargo packages with `Cargo.toml` files."""
 
     def __init__(self):  # noqa: D107
+        """
+        Initialize the CargoPackageIdentification.
+
+        This method calls the __init__ method of the parent class PackageIdentificationExtensionPoint
+        and checks the version compatibility.
+        """
         super().__init__()
         satisfies_version(
             PackageIdentificationExtensionPoint.EXTENSION_POINT_VERSION,

colcon_cargo/task/cargo/build.py

@@ -19,10 +19,25 @@ class CargoBuildTask(TaskExtensionPoint):
     """Build Cargo packages."""
 
     def __init__(self):  # noqa: D107
+        """
+        Initialize the CargoBuildTask.
+
+        This method calls the __init__ method of the parent class TaskExtensionPoint
+        and checks the version compatibility.
+        """
         super().__init__()
         satisfies_version(TaskExtensionPoint.EXTENSION_POINT_VERSION, '^1.0')
 
     def add_arguments(self, *, parser):  # noqa: D102
+        """
+        Add command-line arguments for the CargoBuildTask.
+
+        This method adds arguments to the parser for passing arguments to Cargo
+        projects and for cleaning the build directory before the build.
+
+        Args:
+            parser: The argument parser to add arguments to.
+        """
         parser.add_argument(
             '--cargo-args',
             nargs='*', metavar='*', type=str.lstrip,
@@ -37,6 +52,20 @@ def add_arguments(self, *, parser):  # noqa: D102
     async def build(  # noqa: D102
         self, *, additional_hooks=None, skip_hook_creation=False
     ):
+        """
+        Build the Cargo package.
+
+        This method builds the Cargo package specified in the context. It sets up
+        the necessary environment, prepares the build directory, invokes the build
+        command, and creates environment scripts if requested.
+
+        Args:
+            additional_hooks: Additional hooks to be executed.
+            skip_hook_creation: Whether to skip creating environment hooks.
+
+        Returns:
+            An integer return code. 0 indicates success, and a non-zero value indicates failure.
+        """
         if additional_hooks is None:
             additional_hooks = []
         args = self.context.args
@@ -86,6 +115,16 @@ async def build(  # noqa: D102
 
     # Overridden by colcon-ros-cargo
     def _prepare(self, env, additional_hooks):
+        """
+        Prepare the build environment.
+
+        This method is intended to be overridden by colcon-ros-cargo.
+        It creates an environment hook for the package's PATH.
+
+        Args:
+            env: The environment to prepare.
+            additional_hooks: Additional hooks to be executed.
+        """
         pkg = self.context.pkg
         additional_hooks += create_environment_hook(
             'cargo_{}_path'.format(pkg.name),
@@ -95,6 +134,18 @@ def _prepare(self, env, additional_hooks):
 
     # Overridden by colcon-ros-cargo
     def _build_cmd(self, cargo_args):
+        """
+        Get the build command for Cargo.
+
+        This method is intended to be overridden by colcon-ros-cargo.
+        It returns the command to run 'cargo install' with the provided arguments.
+
+        Args:
+            cargo_args: Additional arguments to pass to Cargo.
+
+        Returns:
+            A list containing the Cargo build command and its arguments.
+        """
         args = self.context.args
         return [
             CARGO_EXECUTABLE, 'install',

colcon_cargo/task/cargo/test.py

@@ -18,13 +18,39 @@ class CargoTestTask(TaskExtensionPoint):
     """Test Cargo packages."""
 
     def __init__(self):  # noqa: D107
+        """
+        Initialize the CargoTestTask.
+
+        This method calls the __init__ method of the parent class TaskExtensionPoint.
+        """
         super().__init__()
         satisfies_version(TaskExtensionPoint.EXTENSION_POINT_VERSION, '^1.0')
 
     def add_arguments(self, *, parser):  # noqa: D102
+        """
+        Add command-line arguments for the CargoTestTask.
+
+        This method is currently empty and does not add any arguments.
+
+        Args:
+            parser: The argument parser to add arguments to.
+        """
         pass
 
     async def test(self, *, additional_hooks=None):  # noqa: D102
+        """
+        Test the Cargo package.
+
+        This method runs the 'cargo test' command to test the Cargo package specified
+        in the context. It sets up the necessary environment, runs the test command,
+        and handles the test results.
+
+        Args:
+            additional_hooks: Additional hooks to be executed.
+
+        Returns:
+            An integer return code. 0 indicates success, and a non-zero value indicates failure.
+        """
         pkg = self.context.pkg
         args = self.context.args