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

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

On Wed, Oct 5, 2016 at 9:46 AM, Hisham <h@hisham.hm> wrote:
> 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

+1

What brought this to my attention was on page 65 of the PIL the text
insinuates that the io.popen command returns a stream, as well as the
return values specified in the preceding paragraph about os.execute:
"Like os.execute, it runs a system command, but it ALSO connects the
command output...". When I couldn't get error information back (I
don't know, does it work?), I looked at the online reference, which
was no more enlightening.
http://www.lua.org/manual/5.3/manual.html#pdf-io.popen

Anyway, it's been a learning opportunity for me and I have now adopted
LDoc right from the get go of my project for the reasons you mentioned
above. I know I would also fall into the same documentation pattern
otherwise (or no pattern at all!).

Russ