PIL 4 Just Arrived!!!

[Russell Haley <russ.haley@...>]

Ha ha, got my copy today. Damn, no light at my desk! Curse my wretched
luck! tee hee

I've been browsing around a little in the book and it's wonderful.
I've also been recently playing with LDoc and documentation in general
and I've noticed something about lua documentation:

<opinion>
Lua can return any number of different things from one function. This
is a fantastic design feature IMHO. Many of the APIs that I see make
use of it. I've been reading documentation of all sorts (as I'm know
everyone here has by the great conversations) and many sources take
the time to spell out the INPUT parameters. However, my non-empirical
findings are  that the documentation on return parameters are
explained in a paragraph about how to use them, NOT a list of what
they are.

This seems to be the case in PIL, but not altogether unexpected as
it's a textbook. But I've noticed this pattern in cqueues, penlight,
and others (two most recent). This is NOT a criticism of their
excellent documentation work. This is simply something I have noticed
while trying to absorb APIs.
</opinion>

Is this an artifact of C based tools? Or is there something I have
missed? I'm here to learn so please prove me incorrect. I am I suppose
"testing my hypothesis".

Thoughts?
Russ