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

[Dirk Laurie <dirk.laurie@...>]

2016-10-01 8:52 GMT+02:00 steve donovan <steve.j.donovan@gmail.com>:
> On Sat, Oct 1, 2016 at 8:45 AM, Russell Haley <russ.haley@gmail.com> wrote:
>> LDoc allows for multiple return statements. Oh, just found --all for
>> local functions. Ah, the ecstasy of documentation tools!
>
> As Sean says: documentation is hard. Plus, doc tools make it easier to
> believe that you _have_ documented something ;)  (I present Javadoc as
> an example of something that looks like documentation, and LDoc is
> very much in that tradition)
>
> No substitute for clear paragraphs of text, I suppose!

The best one can expect from a tool like LDoc is something that
is, and looks like, very good computer-generated extracts from
comments in a program. Often that is good enough.

The opposite approach is Literate Programming, i.e. your code
is scattered all around your documentation and you have a tool
called tangle or anansi to turn it into a program. I did one large
project in it, and can report that the result is exquiste but the
amount of work is staggering.

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 :-)