[erlang-questions] Erlang documentation -- a modest proposal
Mon Sep 26 07:40:09 CEST 2016
Am 26.09.2016 um 03:53 schrieb Richard A. O'Keefe:
> On 23/09/16 8:36 PM, Lutz Behnke wrote:
>> I would propose a position specific to the reference documentation:
>> 8) Put the documentation in the source code. Use edoc (or similar new
> This doesn't work.
> For why?
> Because there is necessary documentation which is not about any
> particular source file.
> Let's take something outside Erlang as an example.
> I know, let's take the C library.
> It is useful to know that
> if x > 0 then exp(log(x)) is approximately equal to x
> if |x| <= 709 then log(exp(x)) is approximately equal to x.
I would argue, that's what overview.edoc is for, but I see your point.
> (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?
>> And it should a precedent for 3rd party libraries. Java doc/ Doxygen are
>> fairly good examples for wide spread adoption or integration into other
> They are good examples of *adoption*. They are not good examples
> of *supporting good documentation*. I am sick of getting Doxygen
> pukes *instead of* documentation. What good is a list of functions to
> me when I don't yet know what function I need?
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.
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
More information about the erlang-questions