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

Benjamin Peterson benjamin at python.org
Tue Jan 20 04:19:17 CET 2009

On Mon, Jan 19, 2009 at 9:11 PM, Brett Cannon <brett at python.org> wrote:

On Mon, Jan 19, 2009 at 19:01, Benjamin Peterson <benjamin at python.org> wrote:

On Mon, Jan 19, 2009 at 8:24 PM, Brett Cannon <brett at python.org> wrote:

2. Should we start using function annotations? No, I think that information is better stored in the function description. Why? Putting it in the signature makes it very succinct and a simple glance at the doc to see what type/ABC is expected.

Well, I guess it's just not been explored. Feel free to try it out if you wish, though.

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. OK, but that doesn't make it optimal. And that still doesn't answer my question of whether all of those nested brackets are truly necessary.

All I can say is that it is the style/convention.

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. So the 'data' directive turns into any variable, not just a module variables?

"data" is for module level objects. If you're documenting properties or attributes in classes, use "attribute".

-- Regards, Benjamin

More information about the Python-Dev mailing list