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

[steve donovan <steve.j.donovan@...>]

On Sat, Oct 1, 2016 at 4:23 PM, Dirk Laurie <dirk.laurie@gmail.com> wrote:
> What I have been doing more and more, though, is to write the
> documentation as a document on its own concurrently with but
> slightly in advance of the code. I.e. the documentation shows
> the code as it ought to be, not as it is. Only a cynic can argue
> with that :-)

Heh, and it's hard to be a cynic and an open-source developer at the same time.

One of the design goals of LDoc was to allow that kind of 'narrative'
documentation to live together with those code comments, plus nicely
formatted examples. Although a marvel of its kind, we don't regard the
Lua Manual as a good tutorial resource - more like fodder for the
constitutional lawyers ;)

With regard to 'code comments', have a look at a typical Rust library file

https://github.com/rust-lang/rust/blob/master/src/libcore/result.rs

Now _that_ shows dedication...