[ python-Bugs-1185124 ] pydoc doesn't find all module doc strings

[SourceForge.net]

Bugs item #1185124, was opened at 2005-04-18 12:18
Message generated for change (Comment added) made by kjohnson
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1185124&group_id=5470

Category: Python Library
Group: Python 2.4
Status: Open
Resolution: None
Priority: 5
Submitted By: Kent Johnson (kjohnson)
Assigned to: Ka-Ping Yee (ping)
Summary: pydoc doesn't find all module doc strings

Initial Comment:
pydoc.synopsis() attempts to find a module's doc string
by parsing the module text. But the parser only
recognizes strings created with """ and r""". Any other
docstring is ignored.

I've attached a patch against Python 2.4.1 that fixes
pydoc to recognize ''' and r''' strings but really it
should recognize any allowable string format.

----------------------------------------------------------------------

>Comment By: Kent Johnson (kjohnson)
Date: 2005-04-18 20:04

Message:
Logged In: YES 
user_id=49695

I don't know if there are a large number of modules with
triple-single-quoted docstrings. Pydoc will search any
module in site-packages at least, so you have to consider
third-party modules.

At best pydoc is inconsistent - the web browser display uses
the __doc__attribute but search and apropos use synopsis().
It's a pretty simple change to recognize any triple-quoted
string, it seems like a good idea to me...

I have attached a revised patch that uses a regex match so
it works with e.g. uR""" and other variations of triple-quoting.

FWIW this bug report was motivated by this thread on
comp.lang.python:
http://groups-beta.google.com/group/comp.lang.python/browse_frm/thread/e5cfccb7c9a168d7/1c1702e71e1939b0?q=triple&rnum=1#1c1702e71e1939b0


----------------------------------------------------------------------

Comment By: Ka-Ping Yee (ping)
Date: 2005-04-18 18:23

Message:
Logged In: YES 
user_id=45338

PEP 257 recommends: "For consistency, always use """triple
double quotes""" around docstrings."  I think that's why
this was originally written to only look for triple
double-quotes.

Are there a large number of modules written using
triple-single quotes for the module docstring?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1185124&group_id=5470