[Doc-SIG] On David Ascher's Rant

[David Ascher]

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,
>                    
>              StringType=types.StringType):
> 
>     """ 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
parse tree.

> > 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
   markup used. 

> 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:

  Language: Francais-France

--david