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: >> 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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4