[erlang-questions] Erlang documentation -- a modest proposal

[Richard A. O'Keefe]

On 26/09/16 6:40 PM, Lutz Behnke wrote:
>> (For maintenance purposes, I would like to track code
>> changes separately from documentation changes, but that's
>> another issue.)
>
> How do you keep track of source changes making it into doc changes?

I don't understand the question.  If you are talking about a change
to the source code that has a corresponding (but necessarily
different) change to the documentation, then they form a single
commit with a common MR or other identifier (if such are used).
>
> Possibly, my level of expectation is so low, that I find almost any
> published doxygem better that having to pick apart the source drop.
>
> If the user doesn't know what he or she needs yet, then reference docs
> (which I was specifically targetting) are not the right piece of the
> docs for them.

I was thinking of a number of fairly popular open source projects
where there was a sketchy tutorial and then a Doxygen puke (with
many of the functions uncommented, just automatic headers) *instead*
of documentation.

Actually, if you look at source code, there are often cues to be had
from the words inside the functions.

I guess it depends on what you mean by "published Doxygen".
I was meaning "so-called documentation made available to people outside
the project generated using Doxygen."

BTW: I am painfully aware that my own documentation skills leave much
to be desired.