On Wed, Jan 21, 2009 at 13:53, Georg Brandl <g.bra...@gmx.net> wrote: > Brett Cannon schrieb: >> 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? > > As said, it matches directive content with directive headers nicely. > Ben's solution is nice as well, but now that we have 3-space I'd rather > we stick with 3-space (however, if you don't care, I'll not reformat > 4-space indents :) >
=) OK. > Code in code blocks should use 4-space as usual. > >> 2. Should we start using function annotations? > > It's not really supported yet by Sphinx. Also, I don't know if it makes > too much sense, given that it will reinforce the thinking of annotations > as type declarations. > Fine by me. >> 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? > > We've discussed that once on the doc-SIG, and I agreed that the bracketing > is not really pretty, especially if it's heavily nested. Python functions > where it makes sense should use the default-value syntax, while C functions > without kwargs support need to keep the brackets. > That was my thinking. > Making this consistent throughout the docs is no small task, of course. > Nope, but perhaps all new docs should stop their use. >> 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? > > (First, you're confusing "directive" and "role" which led to some confusion > on Benjamin's part.) > > Where is a "var" role documented? If it is, it is a bug. http://docs.python.org/dev/3.0/documenting/markup.html#inline-markup. -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
