Documenting Python code

• see PEP257 spec: https://www.python.org/dev/peps/pep-0257/#specification
  • always use """ even for one-liners, as it makes it easier to expand later
  • write the function purpose below the def line, and don't leave a blank line after it
    • but leave a blank line for a class docstring (whether single or multiline)
  • The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
  • mention the nature of the return value
  • Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description
  • the docstring of a script should be usable as its help message

scikit-learn code is a good example of using multi-line docstrings to describe inputs and outputs of functions