[Asterisk-cvs] asterisk/doc CODING-GUIDELINES,1.12,1.13

[kpfleming at lists.digium.com]

Update of /usr/cvsroot/asterisk/doc
In directory mongoose.digium.com:/tmp/cvs-serv2873/doc

Modified Files:
	CODING-GUIDELINES 
Log Message:
add guidelines for doxygen documentation writing (bug #4417, with mods)


Index: CODING-GUIDELINES
===================================================================
RCS file: /usr/cvsroot/asterisk/doc/CODING-GUIDELINES,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- CODING-GUIDELINES	2 Jun 2005 19:17:04 -0000	1.12
+++ CODING-GUIDELINES	2 Jun 2005 19:38:55 -0000	1.13
@@ -1,4 +1,4 @@
-Asterisk Patch/Coding Guidelines
+== Asterisk Patch/Coding Guidelines ==
 
 To be accepted into the codebase, all non-trivial changes must be
 disclaimed to Digium or placed in the public domain. For more information
@@ -242,3 +242,52 @@
 
 Functions are registered using 'struct ast_custom_function'
 structures and the ast_custom_function_register function.
+
+== Doxygen API Documentation Guidelines ==
+
+When writing Asterisk API documentation the following format should be
+followed.
+
+/*!
+ * \brief Do interesting stuff.
+ * \param thing1 interesting parameter 1.
+ * \param thing2 interesting parameter 2.
+ *
+ * This function does some interesting stuff.
+ *
+ * \return zero on success, -1 on error.
+ */
+int ast_interesting_stuff(int thing1, int thing2)
+{
+	return 0;
+}
+
+Notice the use of the \param, \brief, and \return constructs.  These should be
+used to describe the corresponding pieces of the function being documented.
+Also notice the blank line after the last \param directive.  All doxygen
+comments must be in one /*! */ block.  If the function or struct does not need
+an extended description it can be left out.
+
+Please make sure to review the doxygen manual and make liberal use of the \a,
+\code, \c, \b, \note, \li and \e modifiers as appropriate.
+
+When documenting a 'static' function or an internal structure in a module,
+use the \internal modifier to ensure that the resulting documentation
+explicitly says 'for internal use only'.
+
+Structures should be documented as follows.
+
+/*!
+ * \brief A very interesting structure.
+ */
+struct interesting_struct
+{
+	/*! \brief A data member. */
+	int member1;
+
+	int member2; /*!< \brief Another data member. */
+}
+
+Note that /*! */ blocks document the construct immediately following them
+unless they are written, /*!< */, in which case they document the construct
+preceding them.