Logo AND Algorithmique Numérique Distribuée

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