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-24.08:17:59
SpamBayes Score 0.0050227838
Marked as misclassified No
Message-id <1206346681.88.0.915131574332.issue1038909@psf.upfronthosting.co.za>
In-reply-to
Content
Alexander,

I have no idea why your patch languished.  On the one hand I might have
skipped this if I realized that before.  On the other hand, I did add
something extra, and I might not have had an open mind if I had looked
at yours.  Plus, maybe I got it moving! :)  You made a good enhancement
suggestion.  From the continuing interchange below, it looks like two
minds are better than either one.

Comments on your comments on mine:

2.  Hm, good point.  I do not think pydoc should substitute for PyLint,
but it only makes sense to copy the docs from the same type of function
in an ancestor class: static, class or method, though you are right it
need not matter whether the ancestor is built-in or not, though the
assumption is made that you know about built-in docs - you might only
note the inheritance.  

And again, as I did it, finding any ancestor of the wrong type should
stop the search.

There is one inconsistency with static method docs:  If we are given a
class, and have a static method in it, we can search the inheritance
chain for docs.  Neither of us does this at present, though it looks
easier to add through my access point in docroutine.  On the other hand,
if the top-level request is just to document a static function, there is
a problem, since you cannot identify the class it comes from, not having
an im_class attribute, and hence the documentation may look different
from when it was just a part of the documentation for the class.  I do
not see this as a reason to skip the inheritance chain for a static
method when given it's class: better information in -> better
information out.

3.  I agree people should use doc strings not comments, but if everyone
did that, our versions would have the same effect.  The only difference
is if the coder *does* want to use comments for some reason.  Hence the
question is: do you want to document what people do or push them to code
the way you want?  Ping apparently chose the former approach, so I am
not suggesting changing it.   

Thanks,
Andy
History
Date User Action Args
2008-03-24 08:18:02andyharringtonsetspambayes_score: 0.00502278 -> 0.0050227838
recipients: + andyharrington, ping, isandler, aschmolck, pitrou
2008-03-24 08:18:01andyharringtonsetspambayes_score: 0.00502278 -> 0.00502278
messageid: <1206346681.88.0.915131574332.issue1038909@psf.upfronthosting.co.za>
2008-03-24 08:18:01andyharringtonlinkissue1038909 messages
2008-03-24 08:17:59andyharringtoncreate