/*! 
@page inside_doxygen Documenting SimGrid

@tableofcontents

We use doxygen for our documentation. It's annoying but that's the
best we've found so far. Stop bitching about the doc or the tools, and
start improving the documentation text itself.

Good documentation is rare and there is not much project of which we
can get inspiration. The best exception I know is TikZ and
latex-beamer. I'd be so happy if SimGrid documentation could follow
the organization (and reach half the quality) of the TikZ one. But
anyway. As they say: Documentation is like sex; when it's not good
it's still better than nothing and when it's good it's very very good.

@section inside_doxygen_module Adding a new module to the reference guide

If you add a new file to the project, you want to document it. It's
more urgent if it's user-visible, but it should be done in any case if
possible.

@subsection inside_doxygen_module_create Declaring the module to doxygen

First declare your sub-module in the corresponding
(project)/doc/doxygen/module-(enclosing module).doc Two edits are
needed in this file: 

@li Most of the enclosing modules (xbt, msg, sd, etc) have a manually
    maintained table of contents as content of the module main page,
    at the top of the corresponding file. You want to add a reference to
    your sub-module there. For that, simply add something like the
    following. The dash (-) will help building item lists. The ref
    command requests for a link to your module, that is identified
    with the word after that (here, I used xbt_cunit as a sub-module
    identifier.
@verbatim
 - @ref XBT_cunit
@endverbatim

@li Create your module below in the file as follows. the first world
after the defgroup keyword must be the sub-module identifier you used
above.
@verbatim
     /** @defgroup XBT_cunit Unit testing support */
@endverbatim
Warning, the location of this block decides where it appears in the
documentation. In particular, the order of the defgroups is not
inocuitous at all.

@subsection inside_doxygen_module_populate Adding symbols to your module

Once your group is created and referenced from the group containing
it, you must populate it. For that, edit the corresponding header file
to add something like this near the top.
@verbatim
/** @addtogroup XBT_cunit
  * @brief <write here a one-line description of your module>
  *
  * <Write here an introduction to your module>
  * 
  * @{
  */
  
<all the C declarations of your module>

/** @} */
@endverbatim

Any informative stuff is welcomed in the module introduction, on top.
This includes examples that the users can copy/paste to fit their
needs. If your module is too large to be nicely documented on one
unique page, you may want to split its documentation in sub-modules.
See dynar.h for an example of how to do so. 

Make sure to only include the public declarations of your module. For
example, if you have black magic macro voodoo, you probably have some
symbols that are there only for the compiler, but that the users
should not see. In this case, do not put the symbols you want to hide
between the @ { and @ } markers.

@subsection inside_doxygen_module_document Documenting the symbols of your module

Finally, you naturally need to actually write the documentation of
each public symbol belonging to your module. Macros must naturally be
documented in the header file, but it is prefered to put the
documentation in the source file, alongside with the actual
implementation. It is expected that when the code changes, the chances
to update the doc accordingly are higher if the documentation is near
to the code.

For each symbol, you must provide a one-line description in the
<i>brief</i> doxygen parameter. Please document any non trivial
parameter (but something like "dynar: the provided dynar" is not
considered as an informative documentation and can be omitted), and
give any information you feel useful to the user. In particular, add
links to any other location of the documentation that could provide
interesting additional information.

@section inside_doxygen_page Adding a new page to the user guide

Note that doxygen provides two hierarchies that cannot be intermixed.
Groups are used to build a reference guide while pages are used for
any other kind of page in the documentation. A module cannot contain
any page, while a page cannot contain any module. That's the doxygen
style.

@subsection inside_doxygen_page_write Writing a new documentation page

The first thing to do to add a new page is to actually write a file
containing the information you want to add. It should be located in
(project)/doc/doxygen and be named (something).doc Its content must be
something like the following:

@verbatim
/** @page <short_name> <title>

@tableofcontents

blah blah blah

@section <short_name_of_section> <title>

blah blah blah

@subsection <short_name_of_subsection> <title>

Even more stuff. Because we love documentation. We all do.

*/
@endverbatim

Don't forget the starting and ending comment signs. Doxygen only takes
documentation that is in comments, even if there is nothing else in
the file. 

Any short names must be uniq as they are used for the <i>ref</i>
commands to build references between parts.

Titles should be chosed wisely, as they are used (1) as section
headers (2) in the table of contents (3) as text of references, unless
people building a reference specify a replacement text as in:
@verbatim
@ref shortname "text to use instead of the title"
@endverbatim

@subsection inside_doxygen_page_doxy Registering a documentation page to doxygen

Edit (project)/doc/Doxyfile.in and add your page to the INPUT
variable. Don't edit the Doxyfile directly, as it is generated
automatically from the Doxyfile.in: your changes would be overwritten.

Also, edit the source file of the page that will englob the newly page
(to add a new page at root level, edit index.doc that declares the
root), and add something like the following. 

@verbatim
@subpage <shortname>
@endverbatim

This allows doxygen to understand about the page hierarchy that you
want to build. It also puts the name of the subpage as a ref would do.
That is why every page in our documentation seem to contain a table of
contents of sub pages even if it dupplicates what's on the left.
That's the doxygen style (but I can live with it).

@subsection inside_doxygen_page_cmake Registering a documentation page to cmake

Ahhh, cmake and doxygen. The perfect combo to bitch about life for a
whole day...

Edit (project)/tools/cmake/DefinePackage.cmake, and add your
newly added page to the DOC_SOURCES. And bitch about these damn tools.

Don't forget to commit your page, so that you can get some git fun to
complete your day.

@section inside_doxygen_image Adding an image to the documentation

If you need to run a command (like fig2dev) to generate your image,
edit tools/cmake/GenerateDoc.cmake and add your command to the
doc target (grep for fig2dev in the file to see
where exactly). Don't forget to add the source of your image to the
archive somehow. You can add it to the list DOC_FIG of
tools/cmake/DefinePackage.cmake.

If your image is ready to use, put your png in doc/webcruft, and
register it to cmake by adding it to the DOC_IMG list of file
tools/cmake/DefinePackage.cmake so that it lands in the archive
distribution. It will also be copied automatically to the documentation.

@section inside_doxygen_website Working on the website

Our website is generated/exported via [orgmode](http://www.orgmode.org), a tool that we use to facilitate our reproducible research.

Get the sources, and start improving the
website now! (There is a README in the repo with more details, 
but it might be outdated. Contact us if you really want to help.)

@verbatim
git clone git://scm.gforge.inria.fr/simgrid/website.git
@endverbatim

@section inside_doxygen_regen Regenerating the documentation

Once you've changed the doc, you want to run doxygen to regenerate the
html output (and maybe the pdf too). Here is how to do this:

@verbatim
make doc # html documentation
make pdf # the result is in doc/latex/simgrid_documentation.pdf
@endverbatim

Once you're satisfyied with the result, refreshing the documentation
on the web pages is very easy, as shown below. A few permission errors
are ok, unfortunately. We should improve things here, but I'm not sure
of how. This @c make target is also provided in the archives we
distribute to the users, but I guess that it's harmless :)

@verbatim
make sync-gforge-doc
@endverbatim

*/