[Python-Dev] Questions/comments on documentation formatting

[Benjamin Peterson]

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