This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author andyharrington
Recipients andyharrington, aschmolck, isandler, ping, pitrou
Date 2008-03-22.23:38:43
SpamBayes Score 0.063076
Marked as misclassified No
Message-id <1206229125.88.0.265147840265.issue1038909@psf.upfronthosting.co.za>
In-reply-to
Content
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
History
Date User Action Args
2008-03-22 23:38:46andyharringtonsetspambayes_score: 0.063076 -> 0.063076
recipients: + andyharrington, ping, isandler, aschmolck, pitrou
2008-03-22 23:38:45andyharringtonsetspambayes_score: 0.063076 -> 0.063076
messageid: <1206229125.88.0.265147840265.issue1038909@psf.upfronthosting.co.za>
2008-03-22 23:38:45andyharringtonlinkissue1038909 messages
2008-03-22 23:38:44andyharringtoncreate