[issue1038909] pydoc method documentation lookup enhancement

[Andy Harrington]

Andy Harrington <andyharrington at users.sourceforge.net> added the comment:

Several points:

Additional note in pydoc output:

I thought that 'inherited' docs should be marked, so I chose to add to
the note for any function that gets docs displayed from an inherited
function:
   ', docs from inherited <inherited class name>'
Alternate verbiage could certainly be used, but I strongly believe that
the substitution should be marked and its source indicated.  This
addition occurs in HTMLDoc.docroutine and TextDoc.docroutine.


Elaboration?

If a user just calls help(<method reference>) or help(<class
reference>), this patch is certainly appropriate.  On the other hand, if
the call is help(<module reference>), and the module includes the
definitions of the inherited classes from which documentation is
'inherited', then there is duplication within the output, which the user
might or might not desire.  To allow a choice would require a change in
parameters or a global flag in pydoc.  A global flag like
allow_doc_redundancy could be set to False to block inherited
documentation when the ancestor function is already putting a copy of
the documentation in the output.  I would be happy to add this change if
requested, but I thought it would be presumptuous of me to just add it
to the requested patch.  

Testing

I added a test specifically for the inherited docs,
test.test_pydoc_inheritance, generating documentaton on 
test.test_pydoc_sample and comparing results to previously generated
results files test/test_pydoc.txt and test/test_pydoc.html.  If further
changes to pydoc cause outward change to the documentation format, run
test_pydoc_inheritance.regenerateData() to replace the result files.

Nothing in the patch in 2.6 dependent.  Users could choose to upgrade
pydoc for 2.5.x

Added file: http://bugs.python.org/file9823/pydoc.PATCH

_____________________________________
Tracker <report at bugs.python.org>
<http://bugs.python.org/issue1038909>
_____________________________________