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

[Sean Conner <sean@...>]

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