Doxygen_files/reference1.html

   1 <div align="center">
   2 <table width="95%" cellpadding="0" cellspacing="0" border="0">
   3 <tr><td>
   4 <a href="../html/index.html">NetRadiant Doxygen Documentation</a>
   5
   6 <a name="top"></a>
   7 <h1>Doxygen Quick Reference</h1>
   8 <hr>
   9 <p align="left">
  10
  11 <h2>Index</h2>
  12         <ol>
  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>
  18         </ol>
  19 </p>
  20
  21 <hr>
  22 <a name="cs"></a>
  23 <h2>1. Commenting Styles</h2>
  24 There are two different <i>styles</i> of commenting that doxygen recognises.
  25 <p align="left">
  26 Qt Style:<br>
  27 <code>
  28 /*!<br>
  29   .... text ....<br>
  30 */<br>
  31 <br>
  32 </code>
  33 Qt Style Single line<br>
  34 <code>
  35 //! .... one line of text ....<br>
  36 </code>
  37 </p>
  38
  39 <p align="left">
  40 JavaDoc Style:<br>
  41 <code>
  42 /**<br>
  43   * .... text ....<br>
  44   */<br>
  45 </code>
  46 <br>
  47 JavaDoc Style Single line<br>
  48 <code>
  49 /// .... one line of text ....<br>
  50 </code>
  51 </p>
  52
  53 <p>
  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
  58         be ignored.<br>
  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.
  61         <p>
  62                 <i>Note: Standard C/C++ comments are ignored by doxygen, but will be included in the code listing
  63                 for that file.  </i>
  64         </p>
  65 </p>
  66 <p align="right"><a href="#top">top</a> </p>
  67 <hr>
  68
  69 <a name="qts"></a>
  70 <h2>2. Qt Style C++ Class Example</h2>
  71 <p>
  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>
  75         <p>
  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>
  79         </p>
  80         <pre>
  81 //! Virtual class to allow plugin operations on entity pairs
  82 /*!
  83   \todo Write more complete documentation for this class so that it's use
  84   is clear
  85
  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
  88   vec3_t
  89 */
  90 class IEpair
  91 {
  92   public:
  93     //! Increment the number of references to this object
  94     virtual void IncRef () = 0;
  95
  96     //! Decrement the reference count
  97     virtual void DecRef () = 0;
  98
  99     //! Get a vector from a key
 100     virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;
 101
 102     //! Get a float from a key
 103     virtual float FloatForKey( char *key ) = 0;
 104
 105     //! Get a string (char *) from a key
 106     virtual char* ValueForKey( char *key ) = 0;
 107
 108     //! Set a key value to char *value
 109     /*!
 110       \param key The (char *) containing the keyname
 111       \param value The (char *) to set the key value to
 112     */
 113     virtual void SetKeyValue( char *key, char *value ) = 0;
 114
 115     //! Get a vec3_t for the entities origin
 116     virtual void GetEntityOrigin( vec3_t vec ) = 0;
 117
 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;
 120 };
 121 </pre>
 122 </p>
 123 <p>
 124         <p align="right"><a href="#top">top</a> </p>
 125         <a name="jds"></a>
 126         <h2>3. JavaDoc Style C++ Class Example</h2>
 127
 128         The same class documented using JavaDoc Style comments
 129 <pre>
 130 /// Virtual class to allow plugin operations on entity pairs
 131 /**
 132   * @todo Write more complete documentation for this class so that it's use
 133   * is clear
 134   *
 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
 137   * vec3_t
 138   */
 139 class IEpair
 140 {
 141   public:
 142     /// Increment the number of references to this object
 143     virtual void IncRef () = 0;
 144
 145     /// Decrement the reference count
 146     virtual void DecRef () = 0;
 147
 148     /// Get a vector from a key
 149     virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;
 150
 151     /// Get a float from a key
 152     virtual float FloatForKey( char *key ) = 0;
 153
 154     /// Get a string (char *) from a key
 155     virtual char* ValueForKey( char *key ) = 0;
 156
 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
 160       */
 161     virtual void SetKeyValue( char *key, char *value ) = 0;
 162
 163     //! Get a vec3_t for the entities origin
 164     virtual void GetEntityOrigin( vec3_t vec ) = 0;
 165
 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;
 168 };
 169 </pre>
 170 </p>
 171 <p align="right"><a href="#top">top</a> </p>
 172 <hr>
 173
 174 <a name="spt"></a>
 175 <h2>4. Special Tags</h2>
 176 <p>
 177         Special tags using the Qt style begin with a " \ ", or using JavaDoc style a " @ " (the two should not be mixed).<br>
 178         <br>
 179         <b>Common special tags</b><br>
 180         <center>
 181         <table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">
 182         <tr><td width="10%" bgcolor="#DDDDDD" align="right">
 183                 <b>author</b>
 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">
 187                 <b>see</b>
 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">
 191                 <b>param</b>
 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">
 195                 <b>return</b>
 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">
 199                 <b>bug</b>
 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">
 203                 <b>note</b>
 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">
 207                 <b>todo</b>
 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">
 212                 <b>version</b>
 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">
 216                 <b>warning</b>
 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">
 220                 <b>brief</b>
 221         </td><td bgcolor="#DDDDDD">
 222                 <i>A single line comment in place of the //! or /// comment.</i>
 223         </td>
 224         </tr>
 225 </table>
 226 </center>
 227 <br>
 228 <p align="right"><a href="#top">top</a></p>
 229 <hr>
 230 <a name="stt"></a>
 231 <h2>5. Structural Tags</h2>
 232 <p>
 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>
 240 </p>
 241 <p>
 242 An example of the \file structural tag:
 243 <pre>
 244 /*! \file iepairs.h
 245     \brief One line documentation for this file
 246     \author Author(s)
 247     Long description of this file
 248 */
 249 </pre>
 250 </p>
 251
 252 <b>Common Structural Tags</b><br><br>
 253 <center>
 254 <table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">
 255         <tr><td width="10%" bgcolor="#DDDDDD" align="right">
 256                 <b>class</b>
 257         </td><td bgcolor="#DDDDDD">
 258                 <i>Documents a class<br>
 259                 eg:<code><br>
 260                 /*! \class IEpair<br>
 261                 \brief Short description of the IEpair class<br>
 262                                 <br>
 263                 Detailed description of the IEpair class<br>
 264                 */<br>
 265                 </code>
 266                 </i>
 267         </td></tr><tr><td bgcolor="#CCCCCC" align="right">
 268                 <b>def</b>
 269         </td><td bgcolor="#CCCCCC">
 270                 <i>Describes a #define<br>
 271                 eg:<code><br>
 272                 /*! \def MAX_VALUE The name of the define<br>
 273                 \brief Description of MAX_VALUE<br>
 274                 */<br>
 275                 </code>
 276                 </i>
 277         </td></tr><tr><td bgcolor="#DDDDDD" align="right">
 278                 <b>file</b>
 279         </td><td bgcolor="#DDDDDD">
 280                 <i>Describes a file<br>
 281                 eg:<code><br>
 282                 /*! \file iepairs.h The name of the file<br>
 283                     \brief Description of the file iepairs.h<br>
 284                                 <br>
 285                                 Details<br>
 286                 */<br>
 287                 </code>
 288                 </i>
 289         </td></tr><tr><td bgcolor="#CCCCCC" align="right">
 290                 <b>struct</b>
 291         </td><td bgcolor="#CCCCCC">
 292                 <i>Documents a struct<br>
 293                 eg:<code><br>
 294                 /*! \struct BTListList_t the name of the struct<br>
 295                   \brief Description of BTListList_t<br>
 296                         <br>
 297                 Details<br>
 298                 */<br>
 299                 </code>
 300                 </i>
 301         </td></tr><tr><td bgcolor="#DDDDDD" align="right">
 302                 <b>var</b>
 303         </td><td bgcolor="#DDDDDD">
 304                 <i>Documents a typedef, variable or enum value<br>
 305                 eg:<code><br>
 306                 /*! \var typedef unsigned int UINT32<br>
 307                   \brief Short description<br>
 308                 */<br>
 309                 </code>
 310                 </i>
 311         </td></tr><tr><td bgcolor="#CCCCCC" align="right">
 312                 <b>fn</b>
 313         </td><td bgcolor="#CCCCCC">
 314                 <i>Documents a function</i>
 315                 eg:<code><br>
 316                 /*! \fn virtual void IEpair::DecRef() = 0;<br>
 317                   \brief Short description of this function<br>
 318                                 <br>
 319                     Detailed description of this function<br>
 320                 */<br>
 321                 </code>
 322                 </i>
 323         </td>
 324         </tr>
 325 </table>
 326 </center>
 327
 328 <br>
 329 <p align="right"><a href="#top">top</a> </p>
 330 <hr>
 331 </td></tr>
 332 </table>
 333 </div>