Hexamorph wrote:
> Hexamorph schrieb:
>> Jay Loden schrieb:
>>> I have to agree with you WRT to the Python documentation, it does tend
>>> to be lacking and difficult to find things at times.
>
> Hmm, I find the Python documentation just excellent. You are
> searching for a *string* related problem? Then just check the
> *string* class. Also try the dir() function, like
> dir(some_string_variable)
>
> If you come from a C++ background this should be familar to you.
> Check the appropriate class before trying some "procedural" way.
>
> Anyway, glad we could help :)
Well, I don't want to start a flamewar or anything like that - after all, I'm
on a Python mailing list, I love coding in Python, and I think it's a great
language. I've just personally been repeatedly frustrated when programming on
the lack of documentation for some modules (including some in the standard
library).
Don't get me wrong, I love the documentation concepts like docstrings, pydoc,
the online HTML docs, etc. What I don't like is how frequently I run into
things that just aren't documented *well* ;) As an example, reading the docs
for the "socket" module repeatedly tells you things like 'see the UNIX manual'
instead of just documenting the appropriate information. I realize these are
simply thin wrappers for C sockets, but that still assumes your audience is
rather intimately familiar with socket programming in C on UNIX.
This isn't just a problem with the socket module, so please don't think I'm
picking on it or singling it out, it's something I've seen a number of places.
e.g. from os.stat:
os.stat = stat(...)
stat(path) -> stat result
Perform a stat system call on the given path.
Ok...and what is the return value? a list? tuple? string? some type of stat
object? dictionary? The only way to find out is to read the os module's source
code or try it to find out. If you were really lucky you might find the related
documentation from class statvfs_result and put two and two together to figure
it out.
One of the items on my very long TODO list is to submit bug reports for items
like the above but it's a long list and I just haven't gotten there yet ;)
-Jay
--
http://mail.python.org/mailman/listinfo/python-list
