[erlang-questions] Erlang documentation -- a modest proposal
Tue Sep 27 01:55:28 CEST 2016
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).
More information about the erlang-questions