Issue550290
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.
Created on 2002-04-29 17:58 by theller, last changed 2022-04-10 16:05 by admin. This issue is now closed.
Files | ||||
---|---|---|---|---|
File name | Uploaded | Description | Edit | |
pydoc.diff | theller, 2002-04-29 17:58 | Patch for pydoc. | ||
stringobject.diff | theller, 2002-05-15 12:51 | Patch for stringobject.c | ||
pydoc2.diff | gvanrossum, 2002-05-21 19:39 | Alternative patch for pydoc |
Messages (15) | |||
---|---|---|---|
msg39755 - (view) | Author: Thomas Heller (theller) * | Date: 2002-04-29 17:58 | |
pydoc creates a strange description for the __doc__ member: it prints the doc-string of 'str'. Example: C:\>c:\sf\python\dist\src\PCBuild\python.exe Python 2.3a0 (#29, Apr 15 2002, 18:33:31) [MSC 32 bit (Intel)] on win32 Type "help", "copyright", "credits" or "license" for more information. >>> class O(object): ... "some text" ... >>> import pydoc >>> pydoc.help(O) Help on class O in module __main__: class O(__builtin__.object) | some text | | Data and non-method functions defined here: | | __dict__ = <dict-proxy object at 0x0080D410> | | __doc__ = 'some text' | str(object) -> string | | Return a nice string representation of the object. | If the argument is a string, the return value is the same object. | The attached patch prints the following (also for the HTML output): | __doc__ = 'some text' | The documentation string | |
|||
msg39756 - (view) | Author: Thomas Heller (theller) * | Date: 2002-04-30 08:24 | |
Logged In: YES user_id=11105 The same problem exists for the __module__ attribute. I can update the patch if needed. |
|||
msg39757 - (view) | Author: Thomas Heller (theller) * | Date: 2002-04-30 14:49 | |
Logged In: YES user_id=11105 Please ignore my previous comments. It turns out that the problem is not in pydoc, it is in Python itself. "spam".__doc__ is the same as str.__doc__ (which describes what the callable 'str' does. Is this intended? The side-effect is that pydoc prints unexpected output for class variables. Execute this code to find out: class X: a = "a string" b = 42 import pydoc pydoc.help(X) |
|||
msg39758 - (view) | Author: Thomas Heller (theller) * | Date: 2002-04-30 14:50 | |
Logged In: YES user_id=11105 Please ignore my previous comments. It turns out that the problem is not in pydoc, it is in Python itself. "spam".__doc__ is the same as str.__doc__ (which describes what the callable 'str' does. Is this intended? The side-effect is that pydoc prints unexpected output for class variables. Execute this code to find out: class X: a = "a string" b = 42 import pydoc pydoc.help(X) |
|||
msg39759 - (view) | Author: Guido van Rossum (gvanrossum) * | Date: 2002-05-07 12:34 | |
Logged In: YES user_id=6380 The instance doc is supposed to be the same as the class doc, yes. I suppose the str() __doc__ is not particularly appropriate for string instances. Can you suggest a better wording? (This problem is widespread, I presume, so a generic solution may be in order.) |
|||
msg39760 - (view) | Author: Thomas Heller (theller) * | Date: 2002-05-07 17:06 | |
Logged In: YES user_id=11105 No, I cannot think of a better wording. The problem (as you know) is that we have to cover three cases: the str() function, the str type, and the string instances (same for all the other 'simple' types). Would it be worth to add a _doc field to the PyStringObject structure and add a __doc__ entry to tp_members? |
|||
msg39761 - (view) | Author: Thomas Heller (theller) * | Date: 2002-05-07 17:08 | |
Logged In: YES user_id=11105 Or maybe add a __doc__ tp_member (or whatever) which always returns None? |
|||
msg39762 - (view) | Author: Thomas Heller (theller) * | Date: 2002-05-15 12:51 | |
Logged In: YES user_id=11105 The attatched patch (stringobject.diff) implements this behaviour: The doc string of 'str' is unchanged, but string objects have a __doc__ attribute of None. The same could (and should) be done for int, float, and probably more types as well. |
|||
msg39763 - (view) | Author: Raymond Hettinger (rhettinger) * | Date: 2002-05-15 15:13 | |
Logged In: YES user_id=80475 Since this would also go into int, float, and other places, consider factoring it to abstract.c as PyObject_GenericGetNoneDoc or some such. |
|||
msg39764 - (view) | Author: Guido van Rossum (gvanrossum) * | Date: 2002-05-16 12:36 | |
Logged In: YES user_id=6380 I'm very sympathetic, but have no time to review this just yet. Please don't check in without my approval -- this is awfully deep shit (see the history of the __doc__ descriptor in typeobject.c). |
|||
msg39765 - (view) | Author: Guido van Rossum (gvanrossum) * | Date: 2002-05-21 19:13 | |
Logged In: YES user_id=6380 I think there are actually two issues here: pydoc shows the docstrings for what it calls "data and non-method functions", which usually aren't helpful; and the docstrings for basic types are confusing when retrieved through an instance. For the pydoc issue, I have a different patch (pydoc2.diff). This suppresses the docstring completely unless the value is callable. (Now, I know that callable() is not 100% reliable, but it's close enough for pydoc.) For the other issue, I'm not sure *what* to do. Tim suggests that perhaps for the basic types, x.__doc__ should return None. Opinions? |
|||
msg39766 - (view) | Author: Thomas Heller (theller) * | Date: 2002-05-21 19:24 | |
Logged In: YES user_id=11105 > I think there are actually two issues here: pydoc shows the > docstrings for what it calls "data and non-method > functions", which usually aren't helpful; and the docstrings > for basic types are confusing when retrieved through an > instance. > > For the pydoc issue, I have a different patch > (pydoc2.diff). This suppresses the docstring completely > unless the value is callable. (Now, I know that callable() > is not 100% reliable, but it's close enough for pydoc.) Hm, I see no pydoc2.diff ;-) IMO, pydoc should try to document the _purpose_ of the special attributes (__doc__, __module__, ...) instead of their _value_. > For the other issue, I'm not sure *what* to do. Tim suggests > that perhaps for the basic types, x.__doc__ should return > None. Opinions? That's what my sample patch stringobject.diff does. +1 from me. |
|||
msg39767 - (view) | Author: Guido van Rossum (gvanrossum) * | Date: 2002-05-21 19:39 | |
Logged In: YES user_id=6380 > Hm, I see no pydoc2.diff ;-) Oops, here's pydoc2.diff > IMO, pydoc should try to document the _purpose_ of the > special attributes (__doc__, __module__, ...) instead > of their _value_. Maybe, but aren't there lots of these? Maybe this ought to be table-driven instead of an if-statement for each one. I'll call YAGNI on this one for now; at best it's a separate feature request. > > For the other issue, I'm not sure *what* to do. Tim suggests > > that perhaps for the basic types, x.__doc__ should return > > None. Opinions? > That's what my sample patch stringobject.diff does. > +1 from me. That's what I realized after looking at your string patch. :-) Raymond, do you want to work on finishing this? |
|||
msg39768 - (view) | Author: Thomas Heller (theller) * | Date: 2002-05-21 19:54 | |
Logged In: YES user_id=11105 Guido, after applying pydoc2.diff I'm happy. I retract the "feature request". |
|||
msg39769 - (view) | Author: Guido van Rossum (gvanrossum) * | Date: 2002-05-21 20:58 | |
Logged In: YES user_id=6380 OK, I've checked in pydoc2.diff. I'm not sure if we need to do anything about the docstrings of basic objects; I'll close this bug report, if there's a desire for a change there, somebody can open a new bug report. |
History | |||
---|---|---|---|
Date | User | Action | Args |
2022-04-10 16:05:16 | admin | set | github: 36520 |
2002-04-29 17:58:31 | theller | create |