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

[Stanislaw Klekot]

On Tue, Sep 27, 2016 at 10:49:13AM +1300, Richard A. O'Keefe wrote:
> 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.
> 
> Actually, if you look at source code, there are often cues to be had
> from the words inside the functions.
> 
> 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."

Just running a Doxygen or JavaDoc or EDoc on an unprepared source code
is surely far from enough. I don't consider just listing of functions
and types of their parameters a documentation. Such listing would seem
to be as raw and somehow... naked. I don't leave my code in such state.

On the other hand, all of these tools give a predictable structure to
generated documents, which often corresponds well to how I typically
consume the reference manual. I already know how to navigate them, which
is a big plus.

What I miss in EDoc in particular is a good way to add pages that don't
refer to any particular module, like examples or walkthrough. I worked
out a template of putting dummy, empty modules in ./examples/*.erl and
adding ./examples/ to source path for EDoc, which works well, but it's
an abuse of the application and I would prefer to have a dedicated way.

What I liked the best is Sphinx (a tool formerly dedicated to Python,
now much more universal; already mentioned in this thread). It allows to
write documentation with no autogenerated content, yet there is a way to
embed parts extracted from source code, so it's best of both worlds,
I think. Unfortunately one needs to think documentation's structure
beforehand, so it's a larger effort to start than just running
EDoc/JavaDoc (but totally worth it).

-- 
Stanislaw Klekot