doc/doxygen/inside_doxygen.doc

   1 /*!
   2 @page inside_doxygen Documenting SimGrid
   3
   4 \tableofcontents
   5
   6 We use doxygen for our documentation. It's annoying but that's the
   7 best we've found so far. Stop bitching about the doc or the tools, and
   8 start improving the documentation text itself.
   9
  10 Good documentation is rare and there is not much project of which we
  11 can get inspiration. The best exception I know is TikZ and
  12 latex-beamer. I'd be so happy if SimGrid documentation could follow
  13 the organization (and reach half the quality) of the TikZ one. But
  14 anyway. As they say: Documentation is like sex; when it's not good
  15 it's still better than nothing and when it's good it's very very good.
  16
  17 \section inside_doxygen_module Adding a new module to the reference guide
  18
  19 If you add a new file to the project, you want to document it. It's
  20 more urgent if it's user-visible, but it should be done in any case if
  21 possible.
  22
  23 \subsection inside_doxygen_module_create Declaring the module to doxygen
  24
  25 First declare your sub-module in the corresponding
  26 (project)/doc/doxygen/module-(enclosing module).doc Two edits are
  27 needed in this file:
  28
  29 @li Most of the enclosing modules (xbt, msg, sd, etc) have a manually
  30     maintained table of contents as content of the module main page,
  31     at the top of the corresponding file. You want to add a reference to
  32     your sub-module there. For that, simply add something like the
  33     following. The dash (-) will help building item lists. The ref
  34     command requests for a link to your module, that is identified
  35     with the word after that (here, I used xbt_cunit as a sub-module
  36     identifier.
  37 @verbatim
  38  - @ref XBT_cunit
  39 @endverbatim
  40
  41 @li Create your module below in the file as follows. the first world
  42 after the defgroup keyword must be the sub-module identifier you used
  43 above.
  44 @verbatim
  45      /** @defgroup XBT_cunit Unit testing support */
  46 @endverbatim
  47 Warning, the location of this block decides where it appears in the
  48 documentation. In particular, the order of the defgroups is not
  49 inocuitous at all.
  50
  51 \subsection inside_doxygen_module_populate Adding symbols to your module
  52
  53 Once your group is created and referenced from the group containing
  54 it, you must populate it. For that, edit the corresponding header file
  55 to add something like this near the top.
  56 @verbatim
  57 /** @addtogroup XBT_cunit
  58   * @brief <write here a one-line description of your module>
  59   *
  60   * <Write here an introduction to your module>
  61   *
  62   * @{
  63   */
  64
  65 <all the C declarations of your module>
  66
  67 /** @} */
  68 @endverbatim
  69
  70 Any informative stuff is welcomed in the module introduction, on top.
  71 This includes examples that the users can copy/paste to fit their
  72 needs. If your module is too large to be nicely documented on one
  73 unique page, you may want to split its documentation in sub-modules.
  74 See dynar.h for an example of how to do so.
  75
  76 Make sure to only include the public declarations of your module. For
  77 example, if you have black magic macro voodoo, you probably have some
  78 symbols that are there only for the compiler, but that the users
  79 should not see. In this case, do not put the symbols you want to hide
  80 between the @ { and @ } markers.
  81
  82 \subsection inside_doxygen_module_document Documenting the symbols of your module
  83
  84 Finally, you naturally need to actually write the documentation of
  85 each public symbol belonging to your module. Macros must naturally be
  86 documented in the header file, but it is prefered to put the
  87 documentation in the source file, alongside with the actual
  88 implementation. It is expected that when the code changes, the chances
  89 to update the doc accordingly are higher if the documentation is near
  90 to the code.
  91
  92 For each symbol, you must provide a one-line description in the
  93 <i>brief</i> doxygen parameter. Please document any non trivial
  94 parameter (but something like "dynar: the provided dynar" is not
  95 considered as an informative documentation and can be omitted), and
  96 give any information you feel useful to the user. In particular, add
  97 links to any other location of the documentation that could provide
  98 interesting additional information.
  99
 100 \section inside_doxygen_page Adding a new page to the user guide
 101
 102 Note that doxygen provides two hierarchies that cannot be intermixed.
 103 Groups are used to build a reference guide while pages are used for
 104 any other kind of page in the documentation. A module cannot contain
 105 any page, while a page cannot contain any module. That's the doxygen
 106 style.
 107
 108 \subsection inside_doxygen_page_write Writing a new documentation page
 109
 110 The first thing to do to add a new page is to actually write a file
 111 containing the information you want to add. It should be located in
 112 (project)/doc/doxygen and be named (something).doc Its content must be
 113 something like the following:
 114
 115 @verbatim
 116 /** @page <short_name> <title>
 117
 118 @tableofcontents
 119
 120 blah blah blah
 121
 122 @section <short_name_of_section> <title>
 123
 124 blah blah blah
 125
 126 @subsection <short_name_of_subsection> <title>
 127
 128 Even more stuff. Because we love documentation. We all do.
 129
 130 */
 131 @endverbatim
 132
 133 Don't forget the starting and ending comment signs. Doxygen only takes
 134 documentation that is in comments, even if there is nothing else in
 135 the file.
 136
 137 Any short names must be uniq as they are used for the <i>ref</i>
 138 commands to build references between parts.
 139
 140 Titles should be chosed wisely, as they are used (1) as section
 141 headers (2) in the table of contents (3) as text of references, unless
 142 people building a reference specify a replacement text as in:
 143 @verbatim
 144 @ref shortname "text to use instead of the title"
 145 @endverbatim
 146
 147 \subsection inside_doxygen_page_doxy Registering a documentation page to doxygen
 148
 149 Edit (project)/doc/Doxyfile.in and add your page to the INPUT
 150 variable. Don't edit the Doxyfile directly, as it is generated
 151 automatically from the Doxyfile.in: your changes would be overwritten.
 152
 153 Also, edit the source file of the page that will englob the newly page
 154 (to add a new page at root level, edit index.doc that declares the
 155 root), and add something like the following.
 156
 157 @verbatim
 158 @subpage <shortname>
 159 @endverbatim
 160
 161 This allows doxygen to understand about the page hierarchy that you
 162 want to build. It also puts the name of the subpage as a ref would do.
 163 That is why every page in our documentation seem to contain a table of
 164 contents of sub pages even if it dupplicates what's on the left.
 165 That's the doxygen style (but I can live with it).
 166
 167 \subsection inside_doxygen_page_cmake Registering a documentation page to cmake
 168
 169 Ahhh, cmake and doxygen. The perfect combo to bitch about life for a
 170 whole day...
 171
 172 Edit (project)/tools/cmake/DefinePackage.cmake, and add your
 173 newly added page to the DOC_SOURCES. And bitch about these damn tools.
 174
 175 Don't forget to commit your page, so that you can get some git fun to
 176 complete your day.
 177
 178 \section inside_doxygen_image Adding an image to the documentation
 179
 180 If you need to run a command (like fig2dev) to generate your image,
 181 edit tools/cmake/GenerateDoc.cmake and add your command to the
 182 doc target (grep for fig2dev in the file to see
 183 where exactly). Don't forget to add the source of your image to the
 184 archive somehow. You can add it to the list DOC_FIG of
 185 tools/cmake/DefinePackage.cmake.
 186
 187 If your image is ready to use, put your png in doc/webcruft, and
 188 register it to cmake by adding it to the DOC_IMG list of file
 189 tools/cmake/DefinePackage.cmake so that it lands in the archive
 190 distribution. It will also be copied automatically to the documentation.
 191
 192 \section inside_doxygen_website Working on the website
 193
 194 Our website is generated/exported via [orgmode](http://www.orgmode.org), a tool that we use to facilitate our reproducible research.
 195
 196 Get the sources, and start improving the
 197 website now! (There is a README in the repo with more details,
 198 but it might be outdated. Contact us if you really want to help.)
 199
 200 @verbatim
 201 git clone git://scm.gforge.inria.fr/simgrid/website.git
 202 @endverbatim
 203
 204 \section inside_doxygen_regen Regenerating the documentation
 205
 206 Once you've changed the doc, you want to run doxygen to regenerate the
 207 html output (and maybe the pdf too). Here is how to do this:
 208
 209 @verbatim
 210 make doc # html documentation
 211 make pdf # the result is in doc/latex/simgrid_documentation.pdf
 212 @endverbatim
 213
 214 Once you're satisfyied with the result, refreshing the documentation
 215 on the web pages is very easy, as shown below. A few permission errors
 216 are ok, unfortunately. We should improve things here, but I'm not sure
 217 of how. This @c make target is also provided in the archives we
 218 distribute to the users, but I guess that it's harmless :)
 219
 220 @verbatim
 221 make sync-gforge-doc
 222 @endverbatim
 223
 224 */