[issue13386] Document documentation conventions for optional args
Ezio Melotti
report at bugs.python.org
Sat Nov 12 07:08:41 CET 2011
New submission from Ezio Melotti <ezio.melotti at gmail.com>:
AFAIU the conventions for optional argument in the doc are as follow:
If a function has optional arguments and it accepts keyword arguments, the "func(arg=default)" notation should be used, for example:
str.splitlines(keepends=False)
If a function has optional arguments but it doesn't accept keyword arguments, the "func([arg1])" notation is used instead. This should apply only to some C functions, for example:
str.strip([chars])
The notation "func([arg=default])" should never be used, and "func([arg])" should be used only when keyword args are not accepted.
These rules apply to both Python 2 and Python 3.
A thing that is still not clear is what to do in case the default value is a placeholder (like object(), None, -1) and the actual value is then computed in the function.
----------
assignee: docs at python
components: Documentation
messages: 147469
nosy: docs at python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl
priority: normal
severity: normal
stage: needs patch
status: open
title: Document documentation conventions for optional args
versions: Python 2.7, Python 3.2, Python 3.3
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13386>
_______________________________________
More information about the Python-bugs-list
mailing list