PEP 257 – Docstring Conventions

The aim of this PEP is to standardize the high-level structure of docstrings: what they should contain, and how to say it

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition.

For consistency, always use """triple double quotes""" around docstrings.

Use r"""raw triple double quotes""" if you use any backslashes in your docstrings.

One-line Docstrings

There’s no blank line either before or after the docstring.

Multi-line Docstrings

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.

code:python

def awesome_function():

"""summary line

description

...

"""

it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

The summary line may be on the same line as the opening quotes or on the next line.

"""の行に書かなくてもよい

Insert a blank line after all docstrings (one-line or multi-line) that document a class

クラスのdocstringのあとには空行を入れる（←blackは入れてくる）

the class’s methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line.

The docstring of a script (a stand-alone program) should be usable as its “usage” message