-
Notifications
You must be signed in to change notification settings - Fork 77
Docstrings
Shan E Ahmed Raza edited this page May 3, 2023
·
2 revisions
We use the Google format for docstrings. These are used to generate the documentation via Sphinx and Autodoc, see Documentation. Please take the time to write thorough and helpful docstrings.
A pull request may be rejected if the docstrings are missing or not complete.
To clarify and guide styling see the example below in our 'House Style' examples in addition to the Google style examples.
No Ending Line Break If It Fits On A Single Line
Good:
"""My docstring"""
Bad:
"""My docstring
"""
def function_with_types_in_docstring(param1, param2):
""" Example function with types documented in the docstring.
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
"""
class ExampleClass(object):
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they may be documented here
in an ``Attributes`` section and follow the same formatting as a
function's ``Args`` section. Alternatively, attributes may be documented
inline with the attribute's declaration (see __init__ method below).
Properties created with the ``@property`` decorator should be documented
in the property's getter method.
Attributes:
attr1 (str): Description of `attr1`.
attr2 (:obj:`int`, optional): Description of `attr2`.
"""
def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method.
The __init__ method may be documented in either the class level
docstring, or as a docstring on the __init__ method itself.
Either form is acceptable, but the two should not be mixed. Choose one
convention to document the __init__ method and be consistent with it.
Note:
Do not include the `self` parameter in the ``Args`` section.
Args:
param1 (str): Description of `param1`.
param2 (:obj:`int`, optional): Description of `param2`. Multiple
lines are supported.
param3 (:obj:`list` of :obj:`str`): Description of `param3`.
"""
self.attr1 = param1
self.attr2 = param2
self.attr3 = param3 #: Doc comment *inline* with attribute
#: list of str: Doc comment *before* attribute, with type specified
self.attr4 = ['attr4']
self.attr5 = None
"""str: Docstring *after* attribute, with type specified."""
def __init__(self, msg, code):
self.msg = msg
self.code = code
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings