On Mon, Jan 19, 2009 at 19:01, Benjamin Peterson <benja...@python.org> wrote: > On Mon, Jan 19, 2009 at 8:24 PM, Brett Cannon <br...@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. >
Why? Putting it in the signature makes it very succinct and a simple glance at the doc to see what type/ABC is expected. >> >> 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. >> >> 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? -Brett _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
