Skip to content

Commit 52195ad

Browse files
authored
Be explicit about leading * when documenting *args, **kwargs. (#310)
This seem to be what most docstring involving args/kwargs are doing including the example.py; Though I've seen other project be less consistant, so make the suggestion explicit instead of letting users infer from the example. Other convention I've seen are: - `*xi` , documented as `x1,x2, ..., xn : type` - just the name without the leading `*`/`**`. - prefixing `*` with `\\*`.
1 parent 26850f7 commit 52195ad

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

doc/format.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,18 @@ The sections of a function's docstring are:
213213
x1, x2 : array_like
214214
Input arrays, description of `x1`, `x2`.
215215

216+
When documenting variable length positional, or keyword arguments, leave the
217+
leading star(s) in front of the name::
218+
219+
*args : tuple
220+
Additional arguments should be passed as keyword arguments
221+
**kwargs : dict, optional
222+
Extra arguments to `metric`: refer to each metric documentation for a
223+
list of all possible arguments.
224+
225+
..
226+
above example is from scipy.spatial.distance.pdist
227+
216228
5. **Returns**
217229

218230
Explanation of the returned values and their types. Similar to the

0 commit comments

Comments
 (0)