[Doc-SIG] On David Ascher's Rant

[M.-A. Lemburg]

David Ascher wrote:
> 
> 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.

No, I meant the StringType=types.StringType part: it localizes
symbols which would otherwise be looked up in the global name-
space. I often do this to speed up routines which deal with
static APIs like string.split and string.join, e.g.

def f(x,

      split=string.split,join=string.join):

    ...


The l10n stuff is something which will appear in Python 1.6 --
hopefully that is ;-)

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

I guess doc strings are just as personal to the programmer
as indention or naming styles: you won't get everybody to agree
on one way to do it.

Besides, I don't think this is really needed: as long as the
programmer can provide routines to parse his code everything
should be fine. This could e.g. be implemented by subclassing
a reader implementation which then passes the parsed tokens
to other code processing them for some other use.

Of course, you could provide a few standard markup schemes,
e.g. an XML one and StructuredText one.

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

I was referring to "Language:" being English :-) E.g. my
doc strings in German would look quite silly if I would
insert some English markers in there...

But one could of course simply define a few sets of these
markers which then get chosen by a command line option --
one for each language. Or perhaps simply look for all of them.

Well, anyway, these are just some ideas. I'm not going to
code anything or proceed discussing these things. Fred
is doing a great job and I'll continue to document my
code by hand. Perfect for me ;-)

-- 
Marc-Andre Lemburg
______________________________________________________________________
Y2000:                                                    33 days left
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/