Preferred docstring style

[bluetech]

pytest uses various docstring styles, which also leaks to the documentation, and I'm starting to develop an OCD from this!

I propose we use this style:

def func(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.

    Use proper sentences -- start sentences with capital letters and end with periods.

    Can include annotated documentation:

    :param ArgType arg: an argument which determines stuff.
    :returns the result.
    :rtype Foo
    :raises ValueError
    """

After we agree on a style I'll make a sweep over the code (possibly gradual) to update to it.

[nicoddemus]

Wholeheartedly agree, this has also always annoyed me.

I agree with everything in the style except duplicating the type information when it we already have native type annotation, because Sphinx picks those up correctly.

So I would prefer this:

def func(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.

    Use proper sentences -- start sentences with capital letters and end with periods.

    Can include annotated documentation:

    :param arg: An argument which determines stuff, using proper sentences.
    :returns: The result, using proper sentences.
    :raises ValueError: Detailed information when this can happen, using proper sentences.

	Including types into the annotations above is not necessary when type-hinting is being used (as in this example).
    """

[asottile]

we ~could enforce this if we want, though I usually find flake8-docstrings to be more annoying than it is worth

[nicoddemus]

we ~could enforce this if we want, though I usually find flake8-docstrings to be more annoying than it is worth

I see. I would keep it simple at first, I think have a general directive is better than what we have now.

I think most people agree then. @bluetech would you like to add this to the docs somewhere? I'm not sure were to place it though, we might consider creating a new document with development guidelines.

[bluetech]

I'll find some place to document this when I do the sweep.

@asottile I used pydocstyle in some old project, but there were too many false positives and I removed it. Though there might be some subset of warnings that may be useful. But I suggest we wait until we see if a lot review comments are needed for this before we try to add it.

[bluetech]

@nicoddemus

I agree with everything in the style except duplicating the type information when it we already have native type annotation, because Sphinx picks those up correctly.

From I remember in some previous PR sphinx doesn't linkify the type in an annotation, but I'll check again. Might not be worth the duplication even if it doesn't.

[aklajnert]

@nicoddemus

I agree with everything in the style except duplicating the type information when it we already have native type annotation, because Sphinx picks those up correctly.

From I remember in some previous PR sphinx doesn't linkify the type in an annotation, but I'll check again. Might not be worth the duplication even if it doesn't.

IIRC I was using sphinx-autodoc-typehints extension to show the annotations correctly. Not sure if it will fit here, but might be worth checking.

[hugovk]

pytest uses various docstring styles, which also leaks to the documentation, and I'm starting to develop an OCD from this!

I propose we use this style:

def func(arg: ArgType) -> Foo:
    """Do important stuff.

    More detailed info here, in separate paragraphs from the subject line.

    Use proper sentences -- start sentences with capital letters and end with periods.

    Can include annotated documentation:

    :param ArgType arg: an argument which determines stuff.
    :returns the result.
    :rtype Foo
    :raises ValueError
    """

After we agree on a style I'll make a sweep over the code (possibly gradual) to update to it.

Looks good!

Suggestion: (and no strong opinion either way from me :) using an existing style would mean some are already familiar with it, there's no need to define the style here, and there may be tooling already available (for example, but I've no experience with those).

The above style looks close to the Sphinx docstring format:

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

Other popular styles are Google:

def fetch_smalltable_rows(table_handle: smalltable.Table,
                          keys: Sequence[Union[bytes, str]],
                          require_all_keys: bool = False,
                         ) -> Mapping[bytes, Tuple[str]]:
    """Fetches rows from a Smalltable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.

    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: Optional; If require_all_keys is True only
          rows with values set for all keys will be returned.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}

        Returned keys are always bytes.  If a key from the keys argument is
        missing from the dictionary, then that row was not found in the
        table (and require_all_keys must have been False).

    Raises:
        IOError: An error occurred accessing the smalltable.
    """

And NumPy:

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

[bluetech]

@hugovk Thanks, the Sphinx docstring format looks like what we want. I will probably link to it and add some extra details.

---

Here are some more nitpick details I'm changing, let me know if you feel different.

1. Should we use

   """Return some stuff."""

   or

   """Returns some stuff."""

   I prefer "Return ..." (imperative mood).

2. How to format the :param etc.:

   """
   :param arg: Capital letter with period.
   """

   or

   """
   :param arg: no capital letter, no period
   """

   I prefer the capital-letter version.

3. How to format long :param etc. explanations:

   """
   :param arg: Some very very very very very loooong explanation
      with overflow like this.
   """

   or

   """
   :param arg: Some very very very very very loooong explanation
               with overflow like this.
   """

   or

   """
   :param arg:
       Some very very very very very loooong explanation with overflow
       like this.
   """

   I prefer the last one.

4. General width of of comments.

   I aim for ~80 chars but not strict and won't reflow existing comments unless they are very wide.

[nicoddemus]

1. I usually prefer imperative too, but don't have strong feelings either.
2. Capital letter and period. This is important when you need more than one phrase to explain a parameter.
3. Also prefer the last one: easier to maintain.
4. Agreed, same: aim for around 80 chars.