kj <no.em...@please.post> wrote:
> 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[...]
The docs say:
Draw(image) => Draw instance
Creates an object that can be used to draw in the given image.
It seems pretty obvious that the first argument is an 'image' to me,
and when the lib itself defines an Image class...
You "guessed" this was the case from this prominent example at the top
of the page?
import Image, ImageDraw
im = Image.open("lena.pgm")
draw = ImageDraw.Draw(im)
How much more clear can this be made?
> Sorry for the outburst, but unfortunately, PIL is not alone in
> this. Python is awash in poor documentation. [...]
> I have to conclude that the problem with Python docs
> is somehow "systemic"...
Yes, if everyone else disagrees with you, the problem is obviously
"systemic".
What helps are concrete suggestions to the package maintainers about
how these improvements could be made, rather than huge sprawling
attacks on the state of Python documentation (and trying to tie it
into the state of Python itself) as a whole. Instead, what we get are
huge pointless rants like yours whenever someone finds that something
isn't spelled out for them in exactly the way that they want.
These people are _volunteering_ their effort and their code, all
you're providing is an over-excess of hyperbole and punctuation. What
is frustrating to me is seeing people like yourself spend far more
time slamming these projects than actually contributing useful changes
back.
--
http://mail.python.org/mailman/listinfo/python-list
