[Doc-SIG] DocStrings 0.3: Suggestion for documentation syntax (very long)

[Peter Funk]

Hi!

Moshe Zadka:
[...]
> def cmp(f1, f2, shallow=1,use_statcache=0):
>     """Compare two files.
> 
>     arg name=f1 type=string::
>         First file name
> 
>     arg name=f2 type=string::
>         Second file name
> 
>     arg name=shallow type=bool default=1::
>        Just check stat signature (do not read the files).
> 
>     arg name=use_statcache type=bool default=0::
>         Do not stat() each file directly: go through
>         the statcache module for more efficiency.
> 
>     return type=bool::
>         1 if the files are the same, 0 otherwise.
> 
>     This function uses a cache for past comparisons and the results,
>     with a cache invalidation mechanism relying on stale signatures.
>     Of course, if [arg use_statcache] is true, this mechanism is defeated,
>     and the cache will never grow stale.
> 
>     """
[...]
>     def report_partial_closure(self):
> 		'''Print reports on [arg self] and on [member subdirs]'''
[...]
> Please comment!

I don't like it.  I don't believe, that there will ever exist much
Python sourcecode containing such doc strings.  I'm watching
the CVS-checkin mailing list and Guido has just committed three large
batches of std lib modules containing much nicer and smaller doc strings.
These will definitely set standards for other people writing inline 
doc strings, as soon as Python 1.6 comes out.

I can't imagine, that the average Joe Random Python programmer will 
ever bother to write inline doc in such a complex format as you proposed.

I am sad to see, that you have spend a great deal of energy and time
on this spec.  May be I've missed something important?  Maybe the goal
of the whole effort should have been made clearer?

The 'future direction' chapter of the current Python
documentation and the status report posted by Fred Drake J. recently
in this SIG descibe the goal not so clear (at least not for me).
Maybe I've not enough knowledge the planned workflows when
dealing with python documentation.  

The OOL documentation of Pythons std library is remarkable good and
can only be improved in minor details.  Therefore I can't see what
a 1:1 relation between OOL doc and inline doc strings would buy us?
Sure, there is some content overlap between OOL and doc strings, which
intrduces some double work for the maintainers.  But often the OOL is
more elaborated (so should it be), contains tables and other material,
which would only bloat doc strings and distract from the code.

What about Tkinter?  There is Fredrik Lundhs effort, which is still
incomplete in some minor areas, but was nevertheless a very valuable
reference for me.  Unfortunately it can't be included into the python
distribution because of copyright issues AFAIK.  Inline doc strings are
pratically nonexistent in Tkinter.  Who will ever volunteer to
write some, if they must be written in an ugly and hard to learn
format?

What about free third party packages?  Many have no doc
at all.  Others have rather good documentation (e.g. Pmw which is
only incomplete in some areas).  Other packages have doc strings, but
the format varies much depending on the taste of the author.

That is situation now with an exponetially growing set of new open
source Python packages written all over the world.  I don't believe
that many people are eager to rewrite their doc strings according to
a new spec looking radically other than normal text.

In the meantime Java has Javadoc and its capabilities are remarkable
compared to what Python programmers can use today.

So IMOHO it doesn't make much sense to develop a very complex new grammar
for doc strings.  This effort should be better spend on a set of
simple grammars and modular StructuredText like tools, which are able 
to extract a reasonable doctree structure from existing doc strings.

Danilo's 'python-doc'-Package has taken some steps into this direction.
However I am not really happy with the current implementation, which
still relies heavily on Jim Fultons original StructuredText.py and
does further recognition of tags on the paragraph structure spit out
by StructuredText.  But it is better than gendoc and much better than
having nothing at all.  So far Daniel L. has certainly provided a
good starting point.

May be John Aycocks easy to use generic parser could be used to build
flexible and customizable doc string eaters?  So anybody interested
in his own complicated and sophisticated doc string grammar could
easily hack up his parser, while we can stay with simple and easy to
write doc string formats like those written by Guido and others.

Okay: that was sure a demoralizing rant.  It's just my peronal view.

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60