[Python-Dev] Breaking undocumented API

[Glyph Lefkowitz]

On Nov 16, 2010, at 4:49 PM, Guido van Rossum wrote:

>> PEP 8 isn't nearly visible enough, either.  Whatever the rule is, it needs
>> to be presented with the information itself.  If the rule is that things not
>> documented in the library manual have no compatibility guarantees, then all
>> of the means of getting documentation *other* than looking at the library
>> manual need to indicate this somehow (alternatively, the information
>> shouldn't be duplicated, but I doubt I'll convince anyone of that).
> 
> Assuming people actually read the disclaimers.

I don't think it necessarily needs to be presented as a disclaimer.  There will always be people who just ignore part of the information presented, but the message could be something along the lines of "Here's some basic documentation, but it might be out-of-date or incomplete.  You can find a better reference at <http://helpful-hyperlink.example.com>."  If it's easy to click on the link, I think a lot of people will click on it.  Especially since the library reference really _is_ more helpful than the docstrings, for the standard library.

(IMHO, dir()'s semantics are so weird that it should emit a warning too, like "looking for docs?  please use help()".)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20101116/07bb5385/attachment.html>