[erlang-questions] yet more ranting about Erlang docs

[Richard O'Keefe]

Quite by coincidence, I happened to download Scalaris recently.
It looks like an interesting and useful body of code, but it
really is a textbook example of what's wrong with the JavaDoc
Way of documentation.  The installation process gives you a
directory full to overflowing with html files, every one of them
displaying neatly as a screen full of, well, nothing useful.

This criticism does not apply at all to the architecture
diagrams, which I found very helpful.  But that's not Edoc.

One thing this drove home to me is how many things we need
to know about a component other than "here is a module here
is a function".  Things about the environment.  For example,
there's a Java interface for Scalaris and there's a Ruby
interface, but what exactly is the *Erlang* interface?  It may
be quite obvious to someone who has ever used any DHT from
Erlang, but as someone who hasn't, it's not obvious to me, and
it's not something about the code per se.



>