Bugs item #1185124, was opened at 2005-04-18 05:18 Message generated for change (Comment added) made by ping 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: Ka-Ping Yee (ping) Date: 2005-04-18 13:28 Message: Logged In: YES user_id=45338 I think you're right that if it works for the module summary (using __doc__) then it should work with synopsis(). However, the patch you've added doesn't address the problem properly; instead of handling """ correctly and ignoring ''', it handles both kinds of docstrings incorrectly because it will accept ''' as a match for """ or """ as a match for '''. I'll look at fixing this soon, but feel free to keep prodding me until it gets fixed. ---------------------------------------------------------------------- Comment By: Kent Johnson (kjohnson) Date: 2005-04-18 13: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 11: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 _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
