[Doc-SIG] Re: docstrings for re.py?

[Guido van Rossum]

> On Fri, 9 Jul 1999, Guido van Rossum wrote:
> > You introduced one innovation: additional documentation in a separate
> > __flags_doc__ variable.  I'm not sure how well this works - typically, 
> > automatic doc extraction tools won't know to look there.
> 
> Yes, I'm torn about this.  I guess since docstrings should just be "memory
> joggers," your suggestion of using one line descriptions is correct.

Thanks.

> Are there any guidelines as to the recommended maximum length of
> docstrings?  Is it OK to make them as long as necessary?  That makes it
> harder to read on consoles without scrollback, but there are workarounds. 

No guidelines except "make it as short as possible but no shorter".

Tools are the answer to your second question.

> > Would it make sense to also have the pattern syntax in there somewhere? 
> 
> That's a good idea.  I will add descriptions of the special characters and
> sequences to the module docstring.

Thanks.  You can send an updated patch directly to me.

--Guido van Rossum (home page: http://www.python.org/~guido/)