+++ /dev/null
-/*!
-@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_str as a sub-module
- identifier.
-@verbatim
- - @ref XBT_str
-@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_str String related functions */
-@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_str
- * @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
-
-*/
