Re: Documentation (was Re: PIL 4 Just Arrived!!!)

[Hisham <h@...>]

On 1 October 2016 at 03:32, Sean Conner <sean@conman.org> wrote:
> It was thus said that the Great Russell Haley once stated:
>> 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".

I find this phenomenon unfortunate, and my guess is because they
follow the example of the Lua Reference Manual. Hunting for the
specification of the return values amidst the text is something I
often end up having to do when I read the manual. (And sometimes it is
far from the function definition, see the math and io libraries). The
types of arguments and return values are often implied by the prose,
but not stated.

It puzzles me a bit that the stack positions of the C API functions
are nicely summarized for each function and the return values of the
Lua API functions are not. For this reason I prefer LDoc-style
documentation for APIs: it makes reference documentation more
methodical, and therefore quicker to use.

Another omission in the Lua reference manual is to specify which
functions fail when given extra arguments and which don't.

While I appreciate the shortness of the Lua reference manual, I find
some of this "factoring" in the API sections excessive.

-- Hisham