[Doc-SIG] On David Ascher's Rant
Sat, 27 Nov 1999 09:17:37 -0800 (Pacific Standard Time)
On Sat, 27 Nov 1999, M.-A. Lemburg wrote:
> BTW, in case someone cares, the format I use for docstrings and
> function/method signature goes as follows:
> def normlist(jlist,
> """ Return a normalized joinlist.
> All tuples in the joinlist are turned into real strings. The
> resulting list is a equivalent copy of the joinlist only
> consisting of strings.
> 1. Localizations are split from the true input arguments by
> an empty line or a comment line
What's a localization? Do you really mean L10N stuff? FWIW, I think that
using whitespace in the non-docstring source as a significant delimiter
limits things, as it means that the encoding is not readable from the
> > Straw Proposal 0.1 [da]:
> > """
> > <AUTHOR>David Ascher</AUTHOR>
> > <VERSION>1.0</VERSION>
> > <DATE>20/10/96</DATE>
> > <DESCRIPTION>This is a module with one function in it.</DESCRIPTION>
> > <URI>...</URI>
> > """
> Are you serious about the above ??? Noone is going to write that
> in his docstrings...
It's not my favorite, but Uche mentioned that XML-ish syntax is much
easier to parse. While I don't really grant that point (or rather I think
that the hill needs to be climbed once for all), I want to emphasize:
What I really care most about is a final decision, not the specific
> Looks fine, but there is one catch: not everyone is going to
> write his docstrings in English...
So add another keyword in the module doctring: