1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
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.python.org/pypi/sphinxcontrib-napoleon .)
You can activate this checker by adding the line::
load-plugins=pylint.extensions.docparams
to the ``MASTER`` 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.
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.
|
