[Python-Dev] Questions/comments on documentation formatting (original) (raw)

Brett Cannon 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. http://docs.python.org/dev/3.0/documenting/markup.html#inline-markup. 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 clarity?

"... variables, including function/method arguments, ...".

-Brett

More information about the Python-Dev mailing list