spadarian / docblock-python

Atom plugin to insert documentation blocks for python functions
GNU General Public License v2.0
22 stars 9 forks source link

Don't include type in docblock #24

Closed Kilo59 closed 5 years ago

Kilo59 commented 6 years ago

The commonly used sphinx extension napoleon allows for types to be documented from type annotations without the need to specify types in the docstring. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#type-annotations

It would convenient if there was an option to prevent adding the type.

Example

def my_func(arg1: str, arg2: int) -> str:
    """Short summary.

    Args:
        arg1: Description of parameter `arg1`.
        arg2: Description of parameter `arg2`.

    Returns:
        Description of returned object.
    """
    return arg1 * arg2

Instead of ...

def my_func(arg1: str, arg2: int) -> str:
    """Short summary.

    Args:
        arg1 (str): Description of parameter `arg1`.
        arg2 (int): Description of parameter `arg2`.

    Returns:
        str: Description of returned object.
    """
    return arg1 * arg2

In my limited experience type hinting arguments is more common than annotating the return types.