Speaking of documentation

[Mickael Remond]

Niclas Eklund (nick@REDACTED) wrote:
> 
> 
> Hello!
> 
> Have anyoune looked att Doxygen?
> 
> http://www.stack.nl/~dimitri/doxygen/

We are planning to release our in-house auto-documentation tool
tomorrow.

For the moment it only produce latex output.
We are hoping to add an HTML-hyperlinked result soon.

The principle is very simple: You store information into the comments
with a specific syntax. The comments are parsed to produce the resulting
documentation.

Here are the information we are managing by putting comments in our
source code:
On the module level, we use such comments:
%%----------------------------------------------------------------------
%% HEADER xmnesia
%% COPYRIGHT IDEALX (C) 2000
%% PURPOSE Implements a hierarchical database
%% DESCRIPTION This is the main module for the core of the hierarchical
%%   database.
%%----------------------------------------------------------------------

We are also extracting author, version, and last_modif date from the
Erlang module directive (-author, -vsn, and -last_modified).
We keep the separation with other information because we want those
three specific information to be accessible with the module_info()
function.

On the function level, we use such standard comments:
%%----------------------------------------------------------------------
%% FUNCTION new_element/4
%% PURPOSE Creates a new element in the document.
%% ARGUMENTS
%%   Name         -- String()
%%   DocId        -- doc_id()
%%   Value        -- term()
%%   Attributes   -- term()
%% RETURN VALUE elt_id() | {error, Reason}
%% DESCRIPTION
%%  Extra comments can be put here, if needed.  
%% SEE ALSO
%%   xm_entry:element/4, new_document/1
%%----------------------------------------------------------------------


Maybe in a futur version we will include a way to merge information with
the cross reference tool.

-- 
Mickaël Rémond