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

[Lutz Behnke]

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
>> tool).
>
> 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
>> tools.
>
> 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.

mfg lutz
-- 
Lutz Behnke
Hochschule für Angewandte Wissenschaften Hamburg,
Labor für Allgemeine Informatik,

phone: +49 40 42875-8156    mailto:lutz.behnke@REDACTED
fax  : +49 40 2803770       http://users.informatik.haw-hamburg.de/~sage
Berliner Tor 7, 20099 Hamburg, Germany