--- /dev/null
+<div align="center">\r
+<table width="95%" cellpadding="0" cellspacing="0" border="0">\r
+<tr><td>\r
+<a href="../html/index.html">GtkRadiant Doxygen Documentation</a>\r
+\r
+<a name="top"></a>\r
+<h1>Doxygen Quick Reference</h1>\r
+<hr>\r
+<p align="left">\r
+\r
+<h2>Index</h2>\r
+ <ol>\r
+ <li><a href="#cs">Commenting styles</a></li>\r
+ <li><a href="#qts">Qt Style C++ Class Example</a></li>\r
+ <li><a href="#jds">JavaDoc Style C++ Class Example</a></li>\r
+ <li><a href="#spt">Special Tags</a></li>\r
+ <li><a href="#stt">Structural Tags</a></li>\r
+ </ol>\r
+</p>\r
+\r
+<hr>\r
+<a name="cs"></a>\r
+<h2>1. Commenting Styles</h2>\r
+There are two different <i>styles</i> of commenting that doxygen recognises.\r
+<p align="left">\r
+Qt Style:<br>\r
+<code>\r
+/*!<br>\r
+ .... text ....<br>\r
+*/<br>\r
+<br>\r
+</code>\r
+Qt Style Single line<br>\r
+<code>\r
+//! .... one line of text ....<br>\r
+</code>\r
+</p>\r
+\r
+<p align="left">\r
+JavaDoc Style:<br>\r
+<code>\r
+/**<br>\r
+ * .... text ....<br>\r
+ */<br>\r
+</code>\r
+<br>\r
+JavaDoc Style Single line<br>\r
+<code>\r
+/// .... one line of text ....<br>\r
+</code>\r
+</p>\r
+\r
+<p>\r
+ Doxygen only allows one brief and one detailed description for each declaration/definition.\r
+ If there is a brief description before a declaration, and one before the a definition, only\r
+ the one before the <i>declaration</i> will be used. If the same situation occurs for a detailed\r
+ description the one before the <i>definition</i> is preferred and the one before the declaration will\r
+ be ignored.<br>\r
+ A useful method is to have the brief documentation with the declaration in the header file,\r
+ and the detailed documentation with the definition in the source file.\r
+ <p>\r
+ <i>Note: Standard C/C++ comments are ignored by doxygen, but will be included in the code listing\r
+ for that file. </i>\r
+ </p>\r
+</p>\r
+<p align="right"><a href="#top">top</a> </p>\r
+<hr>\r
+\r
+<a name="qts"></a>\r
+<h2>2. Qt Style C++ Class Example</h2>\r
+<p>\r
+ Here is an example of a C++ class using Qt Style documentation.<br>\r
+ The IEpair class from include/iepairs.h is used here. The html result of using these comments \r
+ can be found <a href="../example/index.html">here</a>.<br>\r
+ <p>\r
+ <i>Note: The resulting html was generated from a single file. If it were generated as part of\r
+ the whole documentation, many of the function names and variables would be hyperlinks to\r
+ their definitions.</i><br>\r
+ </p>\r
+ <pre>\r
+//! Virtual class to allow plugin operations on entity pairs\r
+/*!\r
+ \todo Write more complete documentation for this class so that it's use\r
+ is clear\r
+ \r
+ An interface to entity keys and key pairs that allows plugins to;\r
+ read and write entity keys and key values, get a key value as a\r
+ vec3_t\r
+*/\r
+class IEpair\r
+{\r
+ public:\r
+ //! Increment the number of references to this object\r
+ virtual void IncRef () = 0;\r
+ \r
+ //! Decrement the reference count\r
+ virtual void DecRef () = 0;\r
+ \r
+ //! Get a vector from a key\r
+ virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;\r
+ \r
+ //! Get a float from a key\r
+ virtual float FloatForKey( char *key ) = 0;\r
+ \r
+ //! Get a string (char *) from a key\r
+ virtual char* ValueForKey( char *key ) = 0;\r
+ \r
+ //! Set a key value to char *value\r
+ /*!\r
+ \param key The (char *) containing the keyname\r
+ \param value The (char *) to set the key value to\r
+ */\r
+ virtual void SetKeyValue( char *key, char *value ) = 0;\r
+ \r
+ //! Get a vec3_t for the entities origin\r
+ virtual void GetEntityOrigin( vec3_t vec ) = 0;\r
+ \r
+ //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys\r
+ virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;\r
+};\r
+</pre>\r
+</p>\r
+<p>\r
+ <p align="right"><a href="#top">top</a> </p>\r
+ <a name="jds"></a>\r
+ <h2>3. JavaDoc Style C++ Class Example</h2>\r
+\r
+ The same class documented using JavaDoc Style comments\r
+<pre>\r
+/// Virtual class to allow plugin operations on entity pairs\r
+/**\r
+ * @todo Write more complete documentation for this class so that it's use\r
+ * is clear\r
+ * \r
+ * An interface to entity keys and key pairs that allows plugins to;\r
+ * read and write entity keys and key values, get a key value as a\r
+ * vec3_t\r
+ */\r
+class IEpair\r
+{\r
+ public:\r
+ /// Increment the number of references to this object\r
+ virtual void IncRef () = 0;\r
+ \r
+ /// Decrement the reference count\r
+ virtual void DecRef () = 0;\r
+ \r
+ /// Get a vector from a key\r
+ virtual void GetVectorForKey( char* key, vec3_t vec ) = 0;\r
+ \r
+ /// Get a float from a key\r
+ virtual float FloatForKey( char *key ) = 0;\r
+ \r
+ /// Get a string (char *) from a key\r
+ virtual char* ValueForKey( char *key ) = 0;\r
+ \r
+ /** Set a key value to char *value\r
+ * @param key The (char *) containing the keyname\r
+ * @param value The (char *) to set the key value to\r
+ */\r
+ virtual void SetKeyValue( char *key, char *value ) = 0;\r
+ \r
+ //! Get a vec3_t for the entities origin\r
+ virtual void GetEntityOrigin( vec3_t vec ) = 0;\r
+ \r
+ //! Compute the rotated bounds of the BBox based on "angle" and "angles" keys\r
+ virtual void CalculateRotatedBounds( vec3_t mins, vec3_t maxs ) = 0;\r
+};\r
+</pre>\r
+</p>\r
+<p align="right"><a href="#top">top</a> </p>\r
+<hr>\r
+\r
+<a name="spt"></a>\r
+<h2>4. Special Tags</h2>\r
+<p>\r
+ Special tags using the Qt style begin with a " \ ", or using JavaDoc style a " @ " (the two should not be mixed).<br>\r
+ <br>\r
+ <b>Common special tags</b><br>\r
+ <center>\r
+ <table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">\r
+ <tr><td width="10%" bgcolor="#DDDDDD" align="right">\r
+ <b>author</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>The author or a list of comma separated authors/contributers</i>\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>see</b> \r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>A reference to another class, class member, function, etc...</i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>param</b> \r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>A description of a specific function argument or parameter</i>\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>return</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>A description of the value returned from a function/method</i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>bug</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Starts a paragraph where one or more bugs may be listed.</i>\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>note</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>Starts a paragraph where a note may be entered.</i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>todo</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Starts a paragraph where a TODO item is described.</i><br>\r
+ Note: All TODO items are collated into a separate todo list, each linking to each other\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>version</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>Starts a paragraph where one or more version strings may be entered.</i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>warning</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Starts a paragraph where one or more warning messages may be entered.</i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>brief</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>A single line comment in place of the //! or /// comment.</i>\r
+ </td>\r
+ </tr> \r
+</table>\r
+</center>\r
+<br>\r
+<p align="right"><a href="#top">top</a></p>\r
+<hr>\r
+<a name="stt"></a>\r
+<h2>5. Structural Tags</h2>\r
+<p>\r
+These are used to document a named object, and are not required to be located near that\r
+object definition or declaration. This allows the documentation for an object to be located\r
+anywhere in the doxygen input files. The exception to this rule however, is that these\r
+documentation blocks cannot be within the body of a function or within C style comment blocks.\r
+All structural commands are preceded by either a " \ " or a " @ ", depending on the \r
+documentation style, and require one or more parameters to specify the name of the object\r
+the description is referring to.<br>\r
+</p>\r
+<p>\r
+An example of the \file structural tag:\r
+<pre>\r
+/*! \file iepairs.h\r
+ \brief One line documentation for this file\r
+ \author Author(s)\r
+ Long description of this file\r
+*/\r
+</pre>\r
+</p>\r
+\r
+<b>Common Structural Tags</b><br><br>\r
+<center>\r
+<table width="90%" cellpadding="4" cellspacing="2" border="0" valign="top">\r
+ <tr><td width="10%" bgcolor="#DDDDDD" align="right">\r
+ <b>class</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Documents a class<br>\r
+ eg:<code><br>\r
+ /*! \class IEpair<br>\r
+ \brief Short description of the IEpair class<br>\r
+ <br> \r
+ Detailed description of the IEpair class<br>\r
+ */<br>\r
+ </code>\r
+ </i> \r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>def</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>Describes a #define<br>\r
+ eg:<code><br>\r
+ /*! \def MAX_VALUE The name of the define<br>\r
+ \brief Description of MAX_VALUE<br>\r
+ */<br>\r
+ </code>\r
+ </i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>file</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Describes a file<br>\r
+ eg:<code><br>\r
+ /*! \file iepairs.h The name of the file<br>\r
+ \brief Description of the file iepairs.h<br>\r
+ <br>\r
+ Details<br>\r
+ */<br>\r
+ </code>\r
+ </i>\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>struct</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>Documents a struct<br>\r
+ eg:<code><br>\r
+ /*! \struct BTListList_t the name of the struct<br>\r
+ \brief Description of BTListList_t<br>\r
+ <br>\r
+ Details<br>\r
+ */<br>\r
+ </code>\r
+ </i>\r
+ </td></tr><tr><td bgcolor="#DDDDDD" align="right">\r
+ <b>var</b>\r
+ </td><td bgcolor="#DDDDDD">\r
+ <i>Documents a typedef, variable or enum value<br>\r
+ eg:<code><br>\r
+ /*! \var typedef unsigned int UINT32<br>\r
+ \brief Short description<br>\r
+ */<br>\r
+ </code>\r
+ </i>\r
+ </td></tr><tr><td bgcolor="#CCCCCC" align="right">\r
+ <b>fn</b>\r
+ </td><td bgcolor="#CCCCCC">\r
+ <i>Documents a function</i>\r
+ eg:<code><br>\r
+ /*! \fn virtual void IEpair::DecRef() = 0;<br>\r
+ \brief Short description of this function<br>\r
+ <br>\r
+ Detailed description of this function<br>\r
+ */<br>\r
+ </code>\r
+ </i>\r
+ </td>\r
+ </tr>\r
+</table>\r
+</center>\r
+\r
+<br> \r
+<p align="right"><a href="#top">top</a> </p>\r
+<hr>\r
+</td></tr>\r
+</table>\r
+</div>\r
projects / xonotic / netradiant.git / blobdiff