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

Richard A. O'Keefe ok@REDACTED
Mon Sep 26 03:53:57 CEST 2016



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.

But neither of these is a fact about log(), so they don't belong
in src/libm/src/C/log.c, and neither of these is a fact about
exp(), so they don't belong in src/libm/src/C/exp.c either.
They belong in a documentation file about the elementary
transcendental functions as a group, and there is no one source
file corresponding to that.  (log.c and exp.c have detailed
internal documentation, which users benefit from NOT seeing,
except for the accuracy results.)

For that matter, log() and clog() aren't even in the same
header, yet I would like to see them documented together.

Consider using the syntax tools.  Any overview or examples
you're going to have is likely to span multiple modules.
There is no one source file where it would find a uniquely
fitting home.

If there is no obvious "home" for documentation, it's most
likely going nowhere, and that's a bad thing.

(For maintenance purposes, I would like to track code
changes separately from documentation changes, but that's
another issue.)
>
> 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?



More information about the erlang-questions mailing list