[Doc-SIG] On David Ascher's Rant

[M.-A. Lemburg]

David Ascher wrote:
> 
> 1) The current Python documentation is, in my opinion, just fine.  I think
>    that moving from LaTeX to something more modern is a great idea, and I
>    think that Fred is doing a beautiful job for what is a thankless task.
>    I have no problem of course with the discussion on that topic.

I second that.
 
> 2) IMHO, the single most problematic aspect of Python documentation is
>    the lack of a standard way for programmers to document their code
>    inside the .py file, unlike e.g. POD., and that is a shame.  If nothing
>    else, I think that lacking this standard is one of the reasons for the
>    lack of docstrings.  If there was a good standard, then the use of
>    docstrings already made in IDLE and Pythonwin (which is wonderful)
>    could be made even deeper and richer, leading to a snowballing effect.
> 
>    There is at least one proposal to index in-code Python docstrings
>    with TeX-like commands.  In my opinion, anything that full of
>    backslashes and braces will never fly in the Python community.

I don't think people will start to write TeX in their docstrings...
after all not everyone can read plain TeX and will get pretty
confused about all those backslashes and curly brackets.

IMHO, a clean plain text approach goes much further; together
with some conventions on how to format this text and intelligent
tools to extract the information encoded by those conventions
will certainly make the writing docstrings much more popular.

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

2. The first line in the docstring includes a short description
   of what the function does.

3. The remaining lines are used for more detailed descriptions.

Additional markup e.g. for cross referencing would be nice
but shouldn't look awkward. One way to do this would be:

a. use .method() for methods of the same class
b. use Class.method() for methods of other classes
c. use *name for referencing defined names in the current context,
   e.g. class names, parameter names, module names, etc.
d. methods/functions which don't have docstrings shouldn't go
   into the automatic documentation output (this feature is often
   forgotten: you may not want to document certain parts of
   you module for some reason)

and so on...

> 3) Programmers in general, smart programmers especially, try to "think
>    out" all of the possible uses for something before they start to design
>    it.  That's why God Invented Managers and deadlines.  We need one or
>    the other.

Right. And it's even worse in the Python community: they first try
to prove NP-completeness rather than think about good reasonable
approaches for the common case.

> 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>
>   """
> 
>   def len(input):
>     """\
>     <DESCRIPTION> Returns the length of the input sequence </DESCRIPTION>
>     <ARGUMENT name="input" type=sequence>
>         The input sequence
>     </ARGUMENT>
>     <RETURNTYPE> IntType </RETURNTYPE>
>     <INDEXWITH>len, lenth, ln</INDEXWIDTH>
>     """
>     ...

Are you serious about the above ??? Noone is going to write that
in his docstrings...
 
> FWIW, I'm really not sure that the above is significantly easier to parse
> in the long run than a more Pythonic:
> 
>   """
>   Author: David Ascher
>   Date: 10/25/99
>   ...
>   """
> 
>   def len(input):
>       """\
>       Description:
>           Returns the length of the input sequence.
> 
>       Arguments:
>          input (sequence) -- The input sequence
> 
>       Return Type: IntType
> 
>       See Also: len, length, ln
>       """
> 
> provided we make explicit exactly the format (just like Python syntax is
> formalized and parseable) and keep the fancy stuff (embedded URLs,
> hyperlinks, etc.) to a single escape code (e.g. like what Mark Hammond was
> pushing for months ago -- see June 1998 archives). That said, what I
> really care most about is a final decision, not the specific markup used.
> That's why I think that what we need is a Guido Stamp Of Approval.

Looks fine, but there is one catch: not everyone is going to
write his docstrings in English...

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