Inline documentation

[Qwlouse]

How should we format the docstrings? I do like the numpy style, but PyCharm doesn't seem to pick up type hints from them.

Example Numpy (no pycharm support):

def foo(a, b):
    """
    One line summary.

    More detailed description

    Parameters
    ----------
    a : int
        Some number

    b : str
        Some text

    Returns
    -------
    str
        The repeated text
    """
    return "".join([b] * a)

Google style:

def foo(a, b):
    """
    One line summary.

    More detailed description

    Args:
        a (int): Some number
        b (str): Some text

    Returns:
        str: The repeated text
    """
    return "".join([b] * a)

Pycharm works fine with reStructuredText:

def foo(a, b):
    """
    One line summary.

    More detailed description

    :param a: Some number
    :type a: int
    :param b: Some text
    :type b: str

    :returns: the repeated text
    :rtype: str
    """
    return "".join([b] * a)

Epytext also works and is very similar except for the usage of @:

def foo(a, b):
    """
    One line summary.

    More detailed description

    @param a: Some number
    @type a: int
    @param b: Some text
    @type b: str

    @returns: the repeated text
    @rtype: str
    """
    return "".join([b] * a)

Sphinx should be able to support all of them.

[flukeskywalker]

I like Numpy and Google styles since they look better in code. Particularly, the Google style, since it's the simplest to write. Are type hints really a big gain for this project? Also, is it likely that PyCharm will soon pick up type hints from other styles?

Also, we could just use annotations to get type hints, regardless of what style we use. Correct?

[Qwlouse]

IMHO type hints help quite a bit with coding and avoiding mistakes, but it is not essential of course.

There is a feature request for PyCharm here: https://youtrack.jetbrains.com/issue/PY-9795 which has about 100 votes (you can only see them when logged in). But it is already over two years old and there is no feedback from Jetbrains.

We could use annotations but that means dropping Python 2 support.

[flukeskywalker]

Alright, let's stick to restructured text then. @untom, Cool?

[untom]

:+1: