[issue1038909] pydoc method documentation lookup enhancement
Changes by Brian Curtin br...@python.org: -- resolution: - rejected stage: - committed/rejected status: open - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Éric Araujo mer...@netwok.org added the comment: Note that similar (duplicate?) #426740 was rejected, so maybe the discussion here is moot. FWIW, I believe using a decorator or a custom metaclass to explicitly inherit a docstring is a good way of achieving what you want. -- nosy: +calvin versions: +Python 3.3 -Python 3.2 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Ron Adam ron_a...@users.sourceforge.net added the comment: I agree. It is close enough to be a duplicate. I suggest closing it. As Ka-Ping noted in the other issue: There's a link to the base class provided if you want to find out what the base class does. This is easy to do if your viewing pydoc output in a web browser. And you can also look at the source code to see any comments. At some point we can consider enhancing the command line help mode to make it easier to do the same. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by Mark Lawrence breamore...@yahoo.co.uk: -- nosy: +ron_adam ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by Terry J. Reedy tjre...@udel.edu: -- versions: +Python 3.2 -Python 2.6 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by Éric Araujo mer...@netwok.org: -- nosy: +merwok ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue1038909 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Andy Harrington [EMAIL PROTECTED] added the comment: 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 _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by Andy Harrington [EMAIL PROTECTED]: Removed file: http://bugs.python.org/file9823/pydoc.PATCH _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Andy Harrington [EMAIL PROTECTED] added the comment: HM, before writing my patch I tested pydoc to see the issue was still there. I did not look at the 2004 patch from aschmolck since it was so old and was clearly not implemented, and brett just listed this issue as one to deal with in 2008. Now I see pydoc.py.PATCH does address the same issue. Comments on the differences: 1. I allow for the case that an ancestor uses the name but not as a method. That *should* stop the search. 2. The 2004 patch does not use inspect.ismethod, but creates its own test. 3. I stuck with the original pydoc convention that comments could substitute for docs. The 2004 patch does not look for comments in ancestors and only uses comments in the current method if no ancestor has docs. That is a difference in design that could be discussed. I am OK with either. 4. The 2004 patch makes its substitution silently. I prefer explicitly noting that the docs are 'inherited'. 5. There is nothing to add to the test package in the 2004 patch. Before looking at the 2004 patch, I replaced my last patch. I just reread the Python source and documentation conventions and changed names and documentation to match. The only change to my previous comments is that test_pydoc_inheritance.regenerateData was renamed test_pydoc_inheritance.regenerate_data One related comment after thinking about the style guides: Should this pydoc change affect the style guide? Is duplication in the source code recommended for 'inherited' docs? Rather than say absolutely nothing in the overriding method, would a standard comment #inherit docs make sense in the source code? In that case a further change to pydoc is needed to recognize this as a special case, where the 'inherited' docs should be substituted. Alternately the search sequence followed in the 2004 patch could be used, which would find the inherited docs before the comment, whatever the comment. Added file: http://bugs.python.org/file9834/pydoc2.PATCH _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Antoine Pitrou [EMAIL PROTECTED] added the comment: Andy, I haven't looked at your patch in great detail but your approach sounds good to me. Probably other people will want to study it and pick on details :) I don't think the #inherit docs proposal brings any added value over the straightforward approach taken in your patch. The fact that the documentation output states when the docstring is inherited seems clear enough. _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Alexander Schmolck [EMAIL PROTECTED] added the comment: Ah, well nice to see this finally going somewhere, although I'm a bit puzzled as to why my patch was clearly not implemented :) Andy, wrt. to your points: 1. Yes, but see below. 2. Are you sure using inspect.ismethod is an improvement? I'm pretty sure I was aware of it and didn't use it for a reason -- from a superficial glance it appears to me that inspect.getmethod is just broken for this purpose. Or do you have a good reason why you'd like to exclude e.g. methods inherited from a builtin? I have no time to check right now, maybe the behavior of ismethod has changed or I remember it wrongly, but in general I think doc-lookup should be oblivious to changes that are transparent at the interface level and whether something is inherited from a builtin or not is should be considered as a mere implementation detail and not at all affect the documentation lookup. 3. I don't feel strongly about this but I'm personally not that keen on using comments as a substitute for docs -- I see no point in conflating these two mechanisms which serve quite different purposes (implementation elucidation vs interface description), especially if the comment is taken from *some other implementation*. 4. Certainly fine by me. 'as _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Andy Harrington [EMAIL PROTECTED] 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 [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Andy Harrington [EMAIL PROTECTED] added the comment: After going to the sprint Monday, I am working on this as my first patch. There is no test file for pydoc. ?? -- nosy: +andyharrington _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Antoine Pitrou added the comment: I agree this behaviour would definitely be useful. -- nosy: +pitrou _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by Antoine Pitrou: -- type: - feature request versions: +Python 2.6 -Python 2.4 _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue1038909] pydoc method documentation lookup enhancement
Changes by A.M. Kuchling: -- keywords: +easy _ Tracker [EMAIL PROTECTED] http://bugs.python.org/issue1038909 _ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
