X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/7da2926d0733ff0683f31aeea176ce71e127264f..a451588d036aa6addbf51c71bbb670f81acfe319:/doc/doxygen/inside_doxygen.doc diff --git a/doc/doxygen/inside_doxygen.doc b/doc/doxygen/inside_doxygen.doc index 7095bed88f..2f6f6e8ca2 100644 --- a/doc/doxygen/inside_doxygen.doc +++ b/doc/doxygen/inside_doxygen.doc @@ -1,47 +1,45 @@ /*! @page inside_doxygen Documenting SimGrid -\tableofcontents +@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. +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 organisation (and reach half the quality) of the TikZ one. But +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 +@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 +@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 +(project)/doc/doxygen/module-(enclosing module).doc Two edits are needed in this file: -@li Most of the englobing modules (xbt, msg, sd, etc) have a manually +@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 submodule there. For that, simply add something like the + 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 submodule + 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 submodule identifier you used +after the defgroup keyword must be the sub-module identifier you used above. @verbatim /** @defgroup XBT_cunit Unit testing support */ @@ -50,7 +48,7 @@ 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 +@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 @@ -72,7 +70,7 @@ to add something like this near the top. 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. +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 @@ -81,7 +79,7 @@ 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 +@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 @@ -97,9 +95,9 @@ 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. +interesting additional information. -\section inside_doxygen_page Adding a new page to the user guide +@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 @@ -107,7 +105,7 @@ 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 +@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 @@ -119,11 +117,11 @@ something like the following: @tableofcontents -blabla bla +blah blah blah @section -bliblublo +blah blah blah @subsection <short_name_of_subsection> <title> @@ -146,7 +144,7 @@ people building a reference specify a replacement text as in: @ref shortname "text to use instead of the title" @endverbatim -\subsection inside_doxygen_page_doxy Registering a documentation page to doxygen +@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 @@ -166,7 +164,7 @@ 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 +@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... @@ -177,7 +175,7 @@ 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 +@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 @@ -191,7 +189,7 @@ 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 +@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. @@ -203,7 +201,7 @@ but it might be outdated. Contact us if you really want to help.) git clone git://scm.gforge.inria.fr/simgrid/website.git @endverbatim -\section inside_doxygen_regen Regenerating the documentation +@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: @@ -216,8 +214,8 @@ make pdf # the result is in doc/latex/simgrid_documentation.pdf 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. A funny thing is that this make target is also provided in the -archives we distribute to the users, but I guess that it's harmless :) +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