How to document a method with parameter(s)?

Question

How to document methods with parameters using Python\'s documentation strings?

EDIT: PEP 257 gives this example:

d         


        

Answer 1

Conventions:

• PEP 257 Docstring Conventions
• PEP 287 reStructuredText Docstring Format

Tools:

• Epydoc: Automatic API Documentation Generation for Python
• sphinx.ext.autodoc – Include documentation from docstrings
• PyCharm has some nice support for docstrings

---

Update: Since Python 3.5 you can use type hints which is a compact, machine-readable syntax:

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

The main advantage of this syntax is that it is defined by the language and that it's unambiguous, so tools like PyCharm can easily take advantage from it.