[Python-Dev] Questions/comments on documentation formatting
Benjamin Peterson
benjamin at python.org
Tue Jan 20 04:01:08 CET 2009
On Mon, Jan 19, 2009 at 8:24 PM, Brett Cannon <brett at python.org> wrote:
> I have been writing up the initial docs for importlib and four things struck me:
>
> 1. Why is three space indents the preferred indentation level?
Because it matches nicely up with the length of directives:
.. somedirective:: blah
^^^
>
> 2. Should we start using function annotations?
No, I think that information is better stored in the function description.
>
> 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?
Actually, the defaults are usually documented in the description not
the signature.
>
> 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?
The docs should be updated. "data" is the one to use now.
--
Regards,
Benjamin
More information about the Python-Dev
mailing list