Changes between Initial Version and Version 1 of DoxygenConventions

Timestamp:

06/03/13 02:09:07 (13 years ago)

Author:

epyon

Comment:

--

DoxygenConventions

@@ +1 @@
+= Doxygen Conventions =
+
+== Comment layouts ==
+
+ * boxed comments have the following layout:
+{{{
+#!cpp
+/**
+ * Boxed comment example.
+ */
+}}}     
+'''Note:''' {{{/**}}} and {{{*/}}} are always in separate lines.
+ * class and function header file comments have the following layout 
+{{{
+#!cpp
+/**
+ * Short class description goes here ending with dot.
+ *
+ * Second sentence is here.
+ * Third sentence is here.
+ */
+class my_class : public base_class
+{
+public:
+    /**
+     * Brief description.
+     *
+     * Function header documentation goes here.
+     *
+     * @param parameter Parameter description.
+     * @return Description of the returned value
+     */
+    int my_function( int parameter );
+    ...
+}
+}}}
+ * these comments are recognized by the Doxygen tool, which can generate HTML documentation for classes. For this reason, the comment has to start with {{{/**}}} instead of {{{/*}}}. Keep the {{{/**}}} and {{{*/}}} in a separate line. 
+
+== Header documentation ==
+
+'''Example''':
+
+{{{
+#!cpp
+// Copyright (C) 2012-2013 ChaosForge / Kornel Kisielewicz
+// http://chaosforge.org/
+//
+// This file is part of NV Libraries.
+// For conditions of distribution and use, see copyright notice in nv.hh
+
+/**
+ * @file file_name.hh
+ * @author Name Surname name.surname(at)mailadress.com
+ * @brief Brief description
+ *
+ */
+
+#ifndef NV_CLASS_NAME_HH
+#define NV_CLASS_NAME_HH
+
+#include <nv/common.hh>
+#include <system_header>
+#include <system_header2>
+
+#include <nv/...>
+#include <nv/...>
+
+namespace nv
+{
+
+// Code goes here...
+
+} // namespace nv
+
+#endif // NV_CLASS_NAME_HH
+
+}}}
+
+'''Notes:'''
+ * author is the person mainly responsible for the class, or the one that wrote the most code of it
+ * copyright date should match current year
+ * use "@" for doxytags, not "\"
+ * file description can be a single brief line if the file constitutes of a single class and the class is well documented
+
+== Class documentation ==
+
+'''Example''':
+{{{
+#!cpp
+/**
+ * An interesting class.
+ * 
+ * A more elaborate multiline class description, 
+ * 
+ * @see another_class
+ */
+class class
+{
+}; // class
+}}}
+'''Notes''':
+ * description should be as elaborate as possible
+ * include any see also information
+ * include any revelant note, todo, warning and pre/post conditions if applicable to the whole class
+ * if class throws exceptions, write about which ones
+
+== Method/function documentation ==
+
+'''Example''':
+{{{
+#!cpp
+/**
+ * A brief description.
+ *
+ * A normal function taking two arguments and returning an integer value.
+ *
+ * @param param an integer argument.
+ * @param another a constant character pointer.
+ * @return A funny value.
+ *
+ * @throws funny_exception on error
+ */
+uint32 funny_function( int param, const char* another );
+}}}
+'''Notes''':
+ * param, return and throw are all mandatory descriptions
+ * any warnings, pre and post conditions, etc. are welcome