標準ライブラリのdocstring

Pythonの標準ライブラリではdocstringが書いてありますが、ライブラリによって引数の書き方が異なっています。

たとえば os.py では

def makedirs(name, mode=0777):
    """makedirs(path [, mode=0777])

    Super-mkdir; create a leaf directory and all intermediate ones.
    Works like mkdir, except that any intermediate path segment (not
    just the rightmost) will be created if it does not exist.  This is
    recursive.
    """

このようにdocstringの一行目に引数を記載していますが、 codeop.py では

def compile_command(source, filename="<input>", symbol="single"):
    r"""Compile a command and determine whether it is incomplete.

    Arguments:

    source -- the source string; may contain \n characters
    filename -- optional filename from which source was read; default
                "<input>"
    symbol -- optional grammar start symbol; "single" (default) or "eval"

    Return value / exceptions raised:

    - Return a code object if the command is complete and valid
    - Return None if the command is incomplete
    - Raise SyntaxError, ValueError or OverflowError if the command is a
      syntax error (OverflowError and ValueError can be produced by
      malformed literals).
    """

このように 引数 -- 説明 の形をとっています。

また、 setuptools の __init__.py では、

    def find(cls, where='.', exclude=(), include=('*',)):
        """Return a list all Python packages found within directory 'where'

        'where' is the root directory which will be searched for packages.  It
        should be supplied as a "cross-platform" (i.e. URL-style) path; it will
        be converted to the appropriate local path syntax.

        'exclude' is a sequence of package names to exclude; '*' can be used
        as a wildcard in the names, such that 'foo.*' will exclude all
        subpackages of 'foo' (but not 'foo' itself).

        'include' is a sequence of package names to include.  If it's
        specified, only the named packages will be included.  If it's not
        specified, all found packages will be included.  'include' can contain
        shell style wildcard patterns just like 'exclude'.
        """

このように 引数 is 説明 の形をとっています。

標準ライブラリ以外のdocstring

標準ライブラリではないですが、有名な requests のdocstringでは、

python
1def request(method, url, **kwargs):
2    """Constructs and sends a :class:`Request <Request>`.
3
4    :param method: method for the new :class:`Request` object.
5    :param url: URL for the new :class:`Request` object.
6    :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
7    :param data: (optional) Dictionary, bytes, or file-like object to send in the body of the :class:`Request`.
8    :param json: (optional) json data to send in the body of the :class:`Request`.
9    :param headers: (optional) Dictionary of HTTP Headers to send with the :class:`Request`.
10    :param cookies: (optional) Dict or CookieJar object to send with the :class:`Request`.
11    （以下略）
12    """

このように :param 引数: 説明 という形をとっています。

どのように書くべきか

上記でみてきたように、ライブラリによってdocstringにおける引数の書き方にはいくつかの種類があります。

Pythonにはdocstringの書き方について書いてある PEP257 がありますが、そこには

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """

このように書け、と書いてありましたが、Pythonistaのみなさんはどのように書くべきだと思われますでしょうか。