Which docstring format should we use?

[stevepiercy]

First which docstring format should we use?

https://stackoverflow.com/a/24385103/2214933

I prefer Google style for its simplicity and adaptability.

Right now the docstrings don't render well.

https://icalendar.readthedocs.io/en/latest/api.html#icalendar.prop.vBoolean

Originally posted by @stevepiercy in https://github.com/collective/icalendar/issues/745#issuecomment-2492574034

[niccokunzmann]

I like the simplicity of the Google format, too. I would give the decision to those who want to do the docs in this way next.

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

[stevepiercy]

We should add an example with a description and an arg with multiple lines. It's not clear where to add line breaks in the example.

I prefer the latter example where it is clear and consistent that indents are 4 spaces.

Documentation should also link to the Google Styleguide.

https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

"""A one-line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

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:
        If 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:

    .. code-block:: python

        {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.

"""