[erlang-questions] Erlang documentation -- a modest proposal
Tue Sep 27 14:19:24 CEST 2016
Am 26.09.2016 um 23:49 schrieb 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).
Yes, if the documentation is done properly and the programmer also has
the necessary skills as a writer.
I have worse eperience that led many project to the state you describe
>> 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.
That is _no_docs_ and should not count ;-) But Erlang currently is far
beyond that state.
> Actually, if you look at source code, there are often cues to be had
> from the words inside the functions.
But it is not presented separately and with a minimal barrier of entry,
have some amount of pretty pringint. Thus pure source code is the method
of last choice for projects that fall into the _no_docs_ category.
> 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.
> erlang-questions mailing list
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,
phone: +49 40 42875-8156 mailto:
fax : +49 40 2803770 http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 5006 bytes
Desc: S/MIME Cryptographic Signature
More information about the erlang-questions