Documentation (was Re: PIL 4 Just Arrived!!!)
[
Date Prev][
Date Next][
Thread Prev][
Thread Next]
[
Date Index]
[
Thread Index]
- Subject: Documentation (was Re: PIL 4 Just Arrived!!!)
- From: Sean Conner <sean@...>
- Date: Sat, 1 Oct 2016 02:32:36 -0400
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