Hi! I sent this to Fred Drake a few weeks ago but got no response. I assume he's busy, or maybe my message never reached him. I hope some of you will have opinions on this (BTW, please Cc: me on any replies, as I am not on python-dev). (Original message below) I was sharing some ideas with Gustavo Niemeyer (who's also receiving a copy of this message) and he told me you'd be the right person to talk to [he was also the one who recommended that I resent it to python-dev]. I'm relatively new to Python, my first project with it started at the beginning of 2004. And, from the start, its documentation bugged me a little. Now I'm completely hooked and am a full-time Python programmer, but I still see the same quirks in documentation. I don't mean to say there's lack of it, but I think it needs some work, it seems quite incomplete. I see some of these characteristics in the tutorial and module documentation, but I'm refering mostly to internal documentation. A simple example:
[].sort.__doc__ L.sort(cmpfunc=None) -- stable sort *IN PLACE*; cmpfunc(x, y) -> -1, 0, 1
While it may seem obvious to somewhat experiencied programmers, it should be explicit, at least for newbies, what "-1, 0, 1" means, in term of comparison (and also what happens if cmpfunc is left out - since it defaults to None, one could think no sorting takes place). But this is relatively minor, and not the best example.
[].remove.__doc__ L.remove(value) -- remove first occurrence of value
What if L doesn't contain 'value', does it raise an exception or does it fail quietly? Does 'remove return anything (the new list, maybe)?
[].pop.__doc__ L.pop([index]) -> item -- remove and return item at index (default last)
What if L is empty? I think you see what I'm getting at: there's a lack of standardization and completeness that can be frustrating, especially for those new to Python and to programming. When I came to Python, I was already a long-time C and Perl programmer, and I got around these things quite easily, mainly by testing at the prompt or sometimes reading source code, but, still, it doesn't seem like a very pythonic way of doing things (explicit better than implicit?). Not to mention clever editors, which could benefit from standard, complete documentation. There are even some modules with empty docstrings, which I think should be strictly forbidden in core modules. For instance:
thread.error.__doc__
As I told Niemeyer, I considered sending documentation patches, but I think a standard should be defined first, and then volunteers (myself included) could sweep over the core language and conform documentation to it. I'm willing to work on it and help however I can, but I wanted to discuss it first (that's why I came to Niemeyer). Well, let me know what you think. Cheers, rbp -- Rodrigo Bernardo Pimentel <rbp@isnomore.net> | GPG KeyId: <0x0DB14978> http://isnomore.net I'll rule you all with an iron fist! [...] You! Obey the fist! -- Invader Zim
On Tuesday 06 September 2005 16:26, Rodrigo Bernardo Pimentel wrote:
I sent this to Fred Drake a few weeks ago but got no response. I assume he's busy, or maybe my message never reached him. I hope some of
It did reach me, but feel into the black hole of "I can't deal with this in the next 5 minutes." Sorry. I do intend to read your message carefully and respond then. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
On Tuesday 06 September 2005 16:26, Rodrigo Bernardo Pimentel wrote:
I sent this to Fred Drake a few weeks ago but got no response. I assume he's busy, or maybe my message never reached him. I hope some of you will have opinions on this (BTW, please Cc: me on any replies, as I am not on python-dev).
Again, I'm sorry I haven't had time to reply until now, but reminders/re-posts like this are certainly a welcome reminder!
(Original message below)
I was sharing some ideas with Gustavo Niemeyer (who's also receiving a copy of this message) and he told me you'd be the right person to talk to [he was also the one who recommended that I resent it to python-dev].
I'll suggest that the Documentation SIG is a better place to discuss this for some reasons, and I've CC'd that list as well.
I'm relatively new to Python, my first project with it started at the beginning of 2004. And, from the start, its documentation bugged me a little. Now I'm completely hooked and am a full-time Python programmer, but I still see the same quirks in documentation.
I don't mean to say there's lack of it, but I think it needs some work, it seems quite incomplete. I see some of these characteristics in the tutorial and module documentation, but I'm refering mostly to internal documentation.
It appears that by "internal" you're referring to the docstrings available from the runtime. I generally only think of those as hints or reminders, and not complete documentation (other minds disagree). For the non-docstring documentation, the same kinds of issues occur, though not always for the same features. I'd categorize the issues you point out into two groups: A) Omissions. You're right; there's a lot of places we haven't been as thorough as we should be. These certainly should be corrected by adding the missing information. B) Vague contracts. There are many places where documentation is omitted because the contracts of the documented feature aren't clearly specified by the code. This may happen for many reasons, but how each should be handled has to be determined on a case-by-case basis. In many cases, it's intentional that edge cases aren't well specified, simply because the treatment hasn't been discussed and decided. This case can usually be resolved by bringing up specific cases; once there's some discussion, useful documentation can be written because the documentation writers learn what the intent was (or the developers have to decide what the contract should be). Historically, I think we've seen a lot of (B) simply because there's an expectation of users will read the source to determine what the feature will do in any given case. As we see more implementations appear, and as the size and range of Python's audience grow, this becomes a less reasonable approach. This is especially the case for features implemented in C, since users are increasingly unlikely to have the C sources handy due to the use of pre-compiled packages on all platforms. [...lots of specific examples elided...]
As I told Niemeyer, I considered sending documentation patches, but I think a standard should be defined first, and then volunteers (myself included) could sweep over the core language and conform documentation to it. I'm willing to work on it and help however I can, but I wanted to discuss it first (that's why I came to Niemeyer).
It would be good to have more specific guidelines for documentation. We've generally avoided trying to specify what exceptions can be raised by various functions or methods, and describe only specific cases that are guaranteed as part of the API. Treatment of edge cases is often left as an accident as well, though not as frequently. As the documentation increasingly becomes the way that programmers learn about the details of the library, we need to think about whether this is the right approach. In addition to this, we should settle the question of completeness of docstrings and document it. Anything missing that should be included according to that decision should then be added. Also, the level of detail regarding edge cases and exceptions that we're willing to make contract should be discussed, and documentation brought up to snuff. This is more likely an issue that will require case-by-case treatment. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
Fred L. Drake, Jr. wrote:
It would be good to have more specific guidelines for documentation.
Would it be possible to have each item in the documentation start out by auto quoting that items __doc__ string? Then omissions, errors, and contradictions would be easy to find and the full documentation would compliment the __doc__ strings rather than repeat them. Cheers, Ron
participants (3)
-
Fred L. Drake, Jr. -
Rodrigo Bernardo Pimentel -
Ron Adam