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

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

On Fri, Sep 30, 2016 at 11:32 PM, 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".
>
>   It's hard to say.  I know that I've started documenting my own Lua code
> and I have documented the return values [1].  I also document the expected
> types of input and output parameters.  I do have my own format because I'm
> not happy with any of the preexisting standards.
>
>> Thoughts?
>
>   Documentation is hard.
>
>   -spc (Let's do some rocketry!  That's easier!)
>
> [1]     For instance:
>
>         https://github.com/spc476/CBOR/blob/master/cbor.lua#L216

Yes, perhaps my sample size is too small. I wouldn't be surprised as
I'm fairly new.

LDoc allows for multiple return statements. Oh, just found --all for
local functions. Ah, the ecstasy of documentation tools!

Russ