diff --git a/colcon_cargo/argcomplete_completer/cargo_args.py b/colcon_cargo/argcomplete_completer/cargo_args.py index 53d5cc4..17466bf 100644 --- a/colcon_cargo/argcomplete_completer/cargo_args.py +++ b/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: diff --git a/colcon_cargo/package_identification/cargo.py b/colcon_cargo/package_identification/cargo.py index 367b399..8b42034 100644 --- a/colcon_cargo/package_identification/cargo.py +++ b/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, diff --git a/colcon_cargo/task/cargo/build.py b/colcon_cargo/task/cargo/build.py index a52ed0a..332d5d2 100644 --- a/colcon_cargo/task/cargo/build.py +++ b/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', diff --git a/colcon_cargo/task/cargo/test.py b/colcon_cargo/task/cargo/test.py index 8b1db36..54b3706 100644 --- a/colcon_cargo/task/cargo/test.py +++ b/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