NRLMMD-GEOIPS / geoips

Main Geolocated Information Processing System code base with basic functionality enabled.
https://nrlmmd-geoips.github.io/geoips/
Other
13 stars 10 forks source link

CLI Docstring don't meet numpy standards, some are inaccurate #458

Open biosafetylvl5 opened 3 months ago

biosafetylvl5 commented 3 months ago

This is in reference to my review of #444, see #444 for all instances - I commented on each.

Here is an example of a docstring not meeting numpy standards:

class GeoipsCommand(abc.ABC):
    """GeoipsCommand Abstract Base Class."""

This breaks the numpy doc string standard.

The first line should be a "one-line summary that does not use variable names or the function name"

The section after should be dedicate to "extended description. This section should be used to clarify functionality, not to discuss implementation detail or background theory, which should rather be explored in the Notes section below. You may refer to the parameters and the function name, but parameter descriptions still belong in the Parameters section."

Here is an example of an inaccurate docstring:

    def add_arguments(self):
        """Add arguments to the list-subparser for the List Packages Command."""
        pass

# no futher method code

and another:

    @property
    def all_possible_subcommand_combinations(self):
        """A list of every possible call signature for the GeoipsTestUnitTest command.
        ...
        # code create a stochastic list of commands that are not comprehensive

Numpy standards: https://numpydoc.readthedocs.io/en/latest/format.html#short-summary

biosafetylvl5 commented 1 month ago

Child of #531

jsolbrig commented 2 weeks ago

@biosafetylvl5, @evrose54 has made a lot of updates to the docstrings for the CLI in the process of doing other PRs. Would you please assess the current docstrings to determine whether any require further updating?