[Python-Dev] Questions/comments on documentation formatting
brett at python.org
Thu Jan 22 19:20:38 CET 2009
On Thu, Jan 22, 2009 at 10:12, Georg Brandl <g.brandl at gmx.net> wrote:
> Brett Cannon schrieb:
>>>> 3. Are brackets for optional arguments (e.g. ``def fxn(a [, b=None [,
>>>> c=None]])``) really necessary when default argument values are
>>>> present? And do we really need to nest the brackets when it is obvious
>>>> that having on optional argument means the rest are optional as well?
>>> We've discussed that once on the doc-SIG, and I agreed that the bracketing
>>> is not really pretty, especially if it's heavily nested. Python functions
>>> where it makes sense should use the default-value syntax, while C functions
>>> without kwargs support need to keep the brackets.
>> That was my thinking.
>>> Making this consistent throughout the docs is no small task, of course.
>> Nope, but perhaps all new docs should stop their use.
> OK. Perhaps we can sprint a bit on automatic replacement at PyCon.
That's a possibility.
>>>> 4. The var directive is not working even though the docs list it as a
>>>> valid directive; so is it still valid and something is broken, or the
>>>> docs need to be updated?
>>> (First, you're confusing "directive" and "role" which led to some confusion
>>> on Benjamin's part.)
>>> Where is a "var" role documented? If it is, it is a bug.
> I assume you're referring to "Variable names are an exception, they should
> be marked simply with *var*."? Do you have suggestions how to improve
"... variables, including function/method arguments, ...".
More information about the Python-Dev