simon-ritchie / numdoclint Goto Github PK

If parent function has no return value and child function has return value, then invalid check result is displayed.

e.g.,

def sample_func_1():

    def sample_func_2():
        return 100

    pass

How to reproduce:

def _run_command(command: str) -> None:
    """
    Run the specified command.

    Parameters
    ----------
    command : str
        The command string.

    Raises
    ------
    Exception
        If the command result code is not 0.
    """
    logger.info(f'Command started: {command}')
    popen = sp.Popen(
        command, shell=True, stdout=sp.PIPE, stderr=sp.STDOUT)
    stdout_bytes: bytes = popen.communicate()[0]
    try:
        stdout: str = stdout_bytes.decode('utf-8')
    except Exception:
        stdout = stdout_bytes.decode('sjis')
    logger.info(stdout)
    if popen.returncode == 0:
        return
    raise Exception(f'Command failed: {popen.returncode}')

Lint result :

While the return value exists in the function, the return value document does not exist in docstring.

For compatibility of old Python environment.

e.g., Parmeters, Retuns.

Check NumPy and Pandas and use a list of section labels (e.g., Parameters, Returns, Raises, Examples, etc) used by theirs.

suffix -> prefix

Hi, I really like the package you've made, and our team is looking at using it to enforce well-written docstrings before new merges are made to the master branch of our codebase.

But we also use black to format all our code, and there's a frustrating incompatibility between the way black formats a function with too many parameters to fit on a line, and the way numdoclint reads that function and its docstring.

(Or at least for a class method, which is the specific example I'm looking at).

Specifically, we have this method:

    def decompress(
        raw_string: str, base64_decode: bool = True, json_load: bool = True
    ) -> str:
        """
        Decompress raw string...

and black makes the closing bracket of the function's parameters line up with the initial def keyword, while numdoclint doesn't seem to recognize the docstring unless the closing bracket is indented like parameters on the line above, eg.

    def decompress(
        raw_string: str, base64_decode: bool = True, json_load: bool = True
        ) -> str:
        """
        Decompress raw string...

Full example here: https://asciinema.org/a/477219?speed=3

If this could be fixed that would be much appreciated!

• Modify function, both single and recursive lint function.
• Add information to README

e.g., argument side is any_value='' and docstring is following:

...
    any_value : str, default ''
...

Probably double quotation as well.

• example 1. sample_arg: Dict[str, int]
• example 2. sample_arg: bool = True

e.g., the argument of query: Dict[str, Any], is targeted by lint.

There is an argument whose explanation does not exist in docstring.
Target argument name: Any]

e.g.,

def sample_func():
    """
    Sample function.
    """

    def sample_func_to_ignore_docstring_check():
        pass

Currently following pattern (i.e., same name function in one module) is not compatible.

def sample_func_1():
    def sample_func_2():
        pass

def sample_func_2():
    pass

TODO:

• Update README.
• Rename
  • get_single_func_info_list.module_path -> path
  • get_single_func_info_list.module_str -> code_str
  • get_func_name_list.py_module_str -> code_str
• Add recursive interface
• Add interface to __init__.py

e.g.

def sample_func(price):
    """
   Invalid Space num Sample.

   Parameters
   ----------
   price : int
       Sample price.
    """
    pass

TODO:

• Add information to README.
• Add tests.
• Add argument validation.