2 <table width="95%" cellpadding="0" cellspacing="0" border="0">
4 <a href="../html/index.html">NetRadiant Doxygen Documentation</a>
7 <h1>Doxygen Quick Reference</h1>
13 <li><a href="#cs">Commenting styles</a></li>
14 <li><a href="#qts">Qt Style C++ Class Example</a></li>
15 <li><a href="#jds">JavaDoc Style C++ Class Example</a></li>
16 <li><a href="#spt">Special Tags</a></li>
17 <li><a href="#stt">Structural Tags</a></li>
23 <h2>1. Commenting Styles</h2>
24 There are two different <i>styles</i> of commenting that doxygen recognises.
33 Qt Style Single line<br>
35 //! .... one line of text ....<br>
47 JavaDoc Style Single line<br>
49 /// .... one line of text ....<br>
54 Doxygen only allows one brief and one detailed description for each declaration/definition.
55 If there is a brief description before a declaration, and one before the a definition, only
56 the one before the <i>declaration</i> will be used. If the same situation occurs for a detailed
57 description the one before the <i>definition</i> is preferred and the one before the declaration will
59 A useful method is to have the brief documentation with the declaration in the header file,
60 and the detailed documentation with the definition in the source file.
62 <i>Note: Standard C/C++ comments are ignored by doxygen, but will be included in the code listing
66 <p align="right"><a href="#top">top</a> </p>
70 <h2>2. Qt Style C++ Class Example</h2>
72 Here is an example of a C++ class using Qt Style documentation.<br>
73 The IEpair class from include/iepairs.h is used here. The html result of using these comments
74 can be found <a href="../example/index.html">here</a>.<br>
76 <i>Note: The resulting html was generated from a single file. If it were generated as part of
77 the whole documentation, many of the function names and variables would be hyperlinks to
78 their definitions.</i><br>
81 //! Virtual class to allow plugin operations on entity pairs
83 \todo Write more complete documentation for this class so that it's use
86 An interface to entity keys and key pairs that allows plugins to;
87 read and write entity keys and key values, get a key value as a
93 //! Increment the number of references to this object
94 virtual void IncRef () = 0;
96 //! Decrement the reference count
97 virtual void DecRef () = 0;
99 //! Get a vector from a key
100 virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;
102 //! Get a float from a key
103 virtual float FloatForKey( char *key ) = 0;
105 //! Get a string (char *) from a key
106 virtual char* ValueForKey( char *key ) = 0;
108 //! Set a key value to char *value
110 \param key The (char *) containing the keyname
111 \param value The (char *) to set the key value to
113 virtual void SetKeyValue( char *key, char *value ) = 0;
115 //! Get a vec3_t for the entities origin
116 virtual void GetEntityOrigin( vec3_t vec ) = 0;
118 //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys
119 virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;
124 <p align="right"><a href="#top">top</a> </p>
126 <h2>3. JavaDoc Style C++ Class Example</h2>
128 The same class documented using JavaDoc Style comments
130 /// Virtual class to allow plugin operations on entity pairs
132 * @todo Write more complete documentation for this class so that it's use
135 * An interface to entity keys and key pairs that allows plugins to;
136 * read and write entity keys and key values, get a key value as a
142 /// Increment the number of references to this object
143 virtual void IncRef () = 0;
145 /// Decrement the reference count
146 virtual void DecRef () = 0;
148 /// Get a vector from a key
149 virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;
151 /// Get a float from a key
152 virtual float FloatForKey( char *key ) = 0;
154 /// Get a string (char *) from a key
155 virtual char* ValueForKey( char *key ) = 0;
157 /** Set a key value to char *value
158 * @param key The (char *) containing the keyname
159 * @param value The (char *) to set the key value to
161 virtual void SetKeyValue( char *key, char *value ) = 0;
163 //! Get a vec3_t for the entities origin
164 virtual void GetEntityOrigin( vec3_t vec ) = 0;
166 //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys
167 virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;
171 <p align="right"><a href="#top">top</a> </p>
175 <h2>4. Special Tags</h2>
177 Special tags using the Qt style begin with a " \ ", or using JavaDoc style a " @ " (the two should not be mixed).<br>
179 <b>Common special tags</b><br>
181 <table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">
182 <tr><td width="10%" bgcolor="#DDDDDD" align="right">
184 </td><td bgcolor="#DDDDDD">
185 <i>The author or a list of comma separated authors/contributers</i>
186 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
188 </td><td bgcolor="#CCCCCC">
189 <i>A reference to another class, class member, function, etc...</i>
190 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
192 </td><td bgcolor="#DDDDDD">
193 <i>A description of a specific function argument or parameter</i>
194 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
196 </td><td bgcolor="#CCCCCC">
197 <i>A description of the value returned from a function/method</i>
198 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
200 </td><td bgcolor="#DDDDDD">
201 <i>Starts a paragraph where one or more bugs may be listed.</i>
202 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
204 </td><td bgcolor="#CCCCCC">
205 <i>Starts a paragraph where a note may be entered.</i>
206 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
208 </td><td bgcolor="#DDDDDD">
209 <i>Starts a paragraph where a TODO item is described.</i><br>
210 Note: All TODO items are collated into a separate todo list, each linking to each other
211 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
213 </td><td bgcolor="#CCCCCC">
214 <i>Starts a paragraph where one or more version strings may be entered.</i>
215 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
217 </td><td bgcolor="#DDDDDD">
218 <i>Starts a paragraph where one or more warning messages may be entered.</i>
219 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
221 </td><td bgcolor="#DDDDDD">
222 <i>A single line comment in place of the //! or /// comment.</i>
228 <p align="right"><a href="#top">top</a></p>
231 <h2>5. Structural Tags</h2>
233 These are used to document a named object, and are not required to be located near that
234 object definition or declaration. This allows the documentation for an object to be located
235 anywhere in the doxygen input files. The exception to this rule however, is that these
236 documentation blocks cannot be within the body of a function or within C style comment blocks.
237 All structural commands are preceded by either a " \ " or a " @ ", depending on the
238 documentation style, and require one or more parameters to specify the name of the object
239 the description is referring to.<br>
242 An example of the \file structural tag:
245 \brief One line documentation for this file
247 Long description of this file
252 <b>Common Structural Tags</b><br><br>
254 <table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">
255 <tr><td width="10%" bgcolor="#DDDDDD" align="right">
257 </td><td bgcolor="#DDDDDD">
258 <i>Documents a class<br>
260 /*! \class IEpair<br>
261 \brief Short description of the IEpair class<br>
263 Detailed description of the IEpair class<br>
267 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
269 </td><td bgcolor="#CCCCCC">
270 <i>Describes a #define<br>
272 /*! \def MAX_VALUE The name of the define<br>
273 \brief Description of MAX_VALUE<br>
277 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
279 </td><td bgcolor="#DDDDDD">
280 <i>Describes a file<br>
282 /*! \file iepairs.h The name of the file<br>
283 \brief Description of the file iepairs.h<br>
289 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
291 </td><td bgcolor="#CCCCCC">
292 <i>Documents a struct<br>
294 /*! \struct BTListList_t the name of the struct<br>
295 \brief Description of BTListList_t<br>
301 </td></tr><tr><td bgcolor="#DDDDDD" align="right">
303 </td><td bgcolor="#DDDDDD">
304 <i>Documents a typedef, variable or enum value<br>
306 /*! \var typedef unsigned int UINT32<br>
307 \brief Short description<br>
311 </td></tr><tr><td bgcolor="#CCCCCC" align="right">
313 </td><td bgcolor="#CCCCCC">
314 <i>Documents a function</i>
316 /*! \fn virtual void IEpair::DecRef() = 0;<br>
317 \brief Short description of this function<br>
319 Detailed description of this function<br>
329 <p align="right"><a href="#top">top</a> </p>