mirror of
https://fuchsia.googlesource.com/third_party/github.com/pylint-dev/pylint
synced 2024-09-20 07:30:13 +00:00
7c915217b0
Co-authored-by: Pierre Sassoulas <pierre.sassoulas@gmail.com>
156 lines
3.8 KiB
ReStructuredText
156 lines
3.8 KiB
ReStructuredText
If you document the parameters of your functions, methods and constructors and
|
|
their types systematically in your code this optional component might
|
|
be useful for you. Sphinx style, Google style, and Numpy style are supported.
|
|
(For some examples, see https://pypi.org/project/sphinxcontrib-napoleon/ .)
|
|
|
|
You can activate this checker by adding the line::
|
|
|
|
load-plugins=pylint.extensions.docparams
|
|
|
|
to the ``MAIN`` section of your ``.pylintrc``.
|
|
|
|
This checker verifies that all function, method, and constructor docstrings
|
|
include documentation of the
|
|
|
|
* parameters and their types
|
|
* return value and its type
|
|
* exceptions raised
|
|
|
|
and can handle docstrings in
|
|
|
|
* Sphinx style (``param``, ``type``, ``return``, ``rtype``,
|
|
``raise`` / ``except``)::
|
|
|
|
def function_foo(x, y, z):
|
|
'''function foo ...
|
|
|
|
:param x: bla x
|
|
:type x: int
|
|
|
|
:param y: bla y
|
|
:type y: float
|
|
|
|
:param int z: bla z
|
|
|
|
:return: sum
|
|
:rtype: float
|
|
|
|
:raises OSError: bla
|
|
'''
|
|
return x + y + z
|
|
|
|
* or the Google style (``Args:``, ``Returns:``, ``Raises:``)::
|
|
|
|
def function_foo(x, y, z):
|
|
'''function foo ...
|
|
|
|
Args:
|
|
x (int): bla x
|
|
y (float): bla y
|
|
|
|
z (int): bla z
|
|
|
|
Returns:
|
|
float: sum
|
|
|
|
Raises:
|
|
OSError: bla
|
|
'''
|
|
return x + y + z
|
|
|
|
* or the Numpy style (``Parameters``, ``Returns``, ``Raises``)::
|
|
|
|
def function_foo(x, y, z):
|
|
'''function foo ...
|
|
|
|
Parameters
|
|
----------
|
|
x: int
|
|
bla x
|
|
y: float
|
|
bla y
|
|
|
|
z: int
|
|
bla z
|
|
|
|
Returns
|
|
-------
|
|
float
|
|
sum
|
|
|
|
Raises
|
|
------
|
|
OSError
|
|
bla
|
|
'''
|
|
return x + y + z
|
|
|
|
|
|
You'll be notified of **missing parameter documentation** but also of
|
|
**naming inconsistencies** between the signature and the documentation which
|
|
often arise when parameters are renamed automatically in the code, but not in
|
|
the documentation.
|
|
**Note:** by default docstrings of private and magic methods are not checked.
|
|
To change this behaviour (for example, to also check ``__init__``) add
|
|
``no-docstring-rgx=^(?!__init__$)_`` to the ``BASIC`` section of your ``.pylintrc``.
|
|
|
|
Constructor parameters can be documented in either the class docstring or
|
|
the ``__init__`` docstring, but not both::
|
|
|
|
class ClassFoo(object):
|
|
'''Sphinx style docstring foo
|
|
|
|
:param float x: bla x
|
|
|
|
:param y: bla y
|
|
:type y: int
|
|
'''
|
|
def __init__(self, x, y):
|
|
pass
|
|
|
|
class ClassBar(object):
|
|
def __init__(self, x, y):
|
|
'''Google style docstring bar
|
|
|
|
Args:
|
|
x (float): bla x
|
|
y (int): bla y
|
|
'''
|
|
pass
|
|
|
|
In some cases, having to document all parameters is a nuisance, for instance if
|
|
many of your functions or methods just follow a **common interface**. To remove
|
|
this burden, the checker accepts missing parameter documentation if one of the
|
|
following phrases is found in the docstring:
|
|
|
|
* For the other parameters, see
|
|
* For the parameters, see
|
|
|
|
(with arbitrary whitespace between the words). Please add a link to the
|
|
docstring defining the interface, e.g. a superclass method, after "see"::
|
|
|
|
def callback(x, y, z):
|
|
'''Sphinx style docstring for callback ...
|
|
|
|
:param x: bla x
|
|
:type x: int
|
|
|
|
For the other parameters, see
|
|
:class:`MyFrameworkUsingAndDefiningCallback`
|
|
'''
|
|
return x + y + z
|
|
|
|
def callback(x, y, z):
|
|
'''Google style docstring for callback ...
|
|
|
|
Args:
|
|
x (int): bla x
|
|
|
|
For the other parameters, see
|
|
:class:`MyFrameworkUsingAndDefiningCallback`
|
|
'''
|
|
return x + y + z
|
|
|
|
Naming inconsistencies in existing parameter and their type documentations are
|
|
still detected.
|