Edoc is the Erlang standard application to document the Erlang API directly inside the Erlang code.
Adding documentation tags in your code
The documentation of your code is automatically generated from special tags that you can put in your code. To get started you can have a look at edoc documentation.
We put our documentation in the doc directory. We only add a file called overview.edoc in this directory. This file is used to generate the main documentation page.
Here is a sample overview.edoc file:
@author Mickaël Rémond <mickael.remond@process-one.net> @copyright 2004-2006 Process-one @version 0.2 @title Jabberlang documentation @doc == Introduction == Jabberlang is a Jabber/XMPP library for Erlang.
Generating an Erlang code documentation
To generate the Erlang documentation of our code, we are reusing the pieces of information from Erlang build files called Emakefile. To do that, we use a modified version of the build tool make.erl, adding the doc function. Here is the function we have added in make.erl:
doc() ->
doc("doc").
doc(DocPath) ->
{ok, Makefiles} = file:consult("Emakefile"),
Files = lists:map(fun({F, _Opts}) -> F end, Makefiles),
edoc:files(Files, [{dir,DocPath}]).
This setting allows us to generate the documentation by simply launching the following Erlang command:
erl -noshell -s make doc -s init stop
Putting a docs target in your makefiles
When including documentation generation in our project Makefile, we usually do the following:
- We define the version number at the start of the Makefile:
VSN = 1.0
- We add a docs target that generate the documentation:
docs: erl -noshell -run edoc_run application \ "'$(APPNAME)'" '"."' '$(DOC_OPTS)' -s init stop
Add Comment