[erlang-questions] Erlang documentation -- a modest proposal
Richard A. O'Keefe
Mon Sep 26 23:49:13 CEST 2016
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*
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.
More information about the erlang-questions