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

[Jeffrey Chang]

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.


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. 


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

Jeff