kj <no.em...@please.post> writes: > Thanks for the pointer, but... > > <RANT> > The documentation I have found for PIL (at > http://www.pythonware.com/library/pil/handbook) is beyond atrocious. > If this is the only way to learn how to use this library, then I > really don't understand how anyone who is not clairvoyant can do it. > > Example: I went to the docs page for ImageDraw. There I find that > the constructor for an ImageDraw.Draw object takes an argument, > but *what* this argument should be (integer? object? string?) is > left entirely undefined. From the examples given I *guessed* that > it was an object of class Image, so I repeated the exercise: I > consulted the docs for the Image module. There I learn that the > constructor for the Image class takes among its parameters one > called "mode" and one called "color", but, here again, what these > parameters are is left completely undefined. ("mode" is left both > syntactically and semantically undefined; "color" is left syntactically > undefined, though the documentation includes a bit by way of semantic > definition of this parameter.)
The first time you read the PIL docs, read the introduction. After that I find the docs pretty easy to use, even though it is true that it is quite terse. E.g. for the mode, look at the "concepts" page in the intro: http://www.pythonware.com/library/pil/handbook/concepts.htm > What's up with this practice of leaving parameters undefined like > this??? Wasn't it obvious to the person writing the Image module > docs that without explaining what these parameters should be the > documentation is nearly useless? Is such poor documentation an > unintended consequence of "duck typing"??? > > Sorry for the outburst, but unfortunately, PIL is not alone in > this. Python is awash in poor documentation. > > The number two complaint I've heard from those who dislike Python > is the poor quality of its documentation, and in particular the > fact that function parameters are typically left undefined, as is > the case in the PIL docs. I like Python a lot, but I have to agree > with this criticism. (The number one complaint has to do with the > syntactic significance of whitespace; of course, I find *this* > criticism silly.) > > What is most frustrating about such poor documentation is that it > is exactly the opposite from what one would expect from the > carefulness and thoroughness found in the PEPs... I find the Python docs very good on the whole. > I have been using Python as my primary scripting language for about > one year, after many years of programming in Perl, and now Python > is my language of choice. But I must say that the documentation > standards I found in the Perl world are *well above* those in the > Python world. This is not to say that Perl documentation is always > excellent; it certainly has its gaps, as one would expect from > volunteer-contributed software. But I don't recall being frustrated > by Perl module docs anywhere nearly as often as I am by Python > module docs. I have to conclude that the problem with Python docs > is somehow "systemic"... I have never programmed in Perl (although I have needed to read some Perl) but over the years I have used C, C++, lisp variants, PHP, Ruby, Caml variants, Haskell, Javascript (and others before the era of the web). I don't find that Python online docs on the web are worse than online docs for any of those languages. -- Arnaud -- http://mail.python.org/mailman/listinfo/python-list
