[Doc-SIG] docstring grammar

[M.-A. Lemburg]

David Ascher wrote:
> 
> > Some notes on the proposal:
> >
> > · Mentioning the function/method signature is ok, but sometimes
> >   not needed since e.g. the byte code has enough information to
> >   deduce the signature from it. This is not true for builtin
> >   function which is probably the reason for all builtin doc
> >   strings to include the signature.
> 
> Right.  It's not true for builtins, extension module functions, and I'm
> not sure how easy it is for JPython code.  I have no problem with somehow
> making it easy to omit those in cases where the information can be
> obtained through the bytecode.

Perhaps we could use a convention: if the first line starts
with a Python identifier followed by '(' and the identifier
matches the name of the doc string owning object (function or
method), then no byte code lookup is done. Otherwise such
a lookup causes a new first line to be prepended to the
processed doc string (with '-> ?' return value).

This should cover most cases.

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