--- /dev/null
+/*!
+@page inside_doxygen Documenting SimGrid
+
+\tableofcontents
+
+We use doxygen for our documentation. This tool is sometimes anoying
+but that's the best we've found so far. Remember, we all bitch about
+doxygen, but at the end of the day, it kinda delivers what we need. So
+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 organisation (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-(englobingmodule).doc Two edits are
+needed in this file:
+
+@li Most of the englobing 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 submodule 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 submodule
+ 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 submodule 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 submodules.
+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 informations.
+
+\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
+
+blabla bla
+
+@section <short_name_of_section> <title>
+
+bliblublo
+
+@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)/buildtools/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 buildtools/Cmake/GenerateDoc.cmake and add your command to the
+simgrid_documentation 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
+buildtools/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
+buildtools/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
+
+Actually, the website is very different from doxygen. It uses a tool
+called jekyll to turn markup-formated text into nice static web pages.
+Jekyll is less annoying than doxygen since it's written in a scripting
+language: you can dynamically add (or change) parts of the tool to
+make it fit your needs. Get the sources, and start improving the
+website now (there is a README in the repo with more details).
+
+@verbatim
+git clone git://scm.gforge.inria.fr/simgrid/website.git
+@endverbatim
+
+
+*/
