diff CODING @ 1645:b9a9a457860d

Update documentation Now it holds a more verbose doxygen description as discussed in mailing list. - Doxygen style description - Small visibility changes - Commit message change

--- a/CODING	Sat Jun 13 19:26:32 2009 +0000
+++ b/CODING	Sat Jun 13 22:19:57 2009 +0000
@@ -1,58 +1,64 @@
 GPL header, in every file, like this:
 
-/** @file relativ/path/with/this/file/name.c
- * Short description of this file.
- * @author Author1
- * @author Author2
+/** \file
+ * \short Short description of this file.
+ * \author Author1
+ * \author Author2
  *
  * Optionaly detailed description of this file
  * on more lines.
  */
-                                                                                
+
 /*
  *  This file is a part of Geeqie project (http://geeqie.sourceforge.net/).
  *  Copyright (C) 2008 - 2009 The Geeqie Team
  *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
- *  the Free Software Foundation; either version 2 of the License, or
- *  (at your option) any later version.
+ *  This program is free software; you can redistribute it and/or modify it
+ *  under the terms of the GNU General Public License as published by the Free
+ *  Software Foundation; either version 2 of the License, or (at your option)
+ *  any later version.
  *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  This program is distributed in the hope that it will be useful, but WITHOUT
+ *  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ *  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ *  more details.
  */
 
 --------------------------------------------------------------------------------
 
 svn change-log:
 
-Use whole sentences begins with Capital letter. For each modification use new line.
-Or you can write the theme, colon and then every change on new line, begin
-with "- ".
+Start with a short summary in the first line (without a dot at the end) followed
+by a empty line. Use whole sentences begins with Capital letter. For each
+modification use new line. Or you can write the theme, colon and then every
+change on new line, begin with "- ".
+
+See also: http://www.tpope.net/node/106
 
 Example:
 
-I did some bugfixes.
-Library:
-- the interface was modified
-- new functions were added
+   I did some bugfixes
+
+   There was the bug that something was wrong. I fixed it.
+
+   Library:
+   - the interface was modified
+   - new functions were added
 
 --------------------------------------------------------------------------------
 
 sources:
 
 Indentation: tabs
-Names of variables & functions: small_letters
-      of defines: CAPITAL_LETTERS
+Names of variables & functions:	 small_letters
+      of defines:		 CAPITAL_LETTERS
 
 Try to use explicit variable and function names.
 
-
 Try not to use macros.
 Use EITHER "struct foo" OR "foo"; never both
 
+
 Conditions, cycles:
 
 if (<cond>)
@@ -67,9 +73,9 @@
 	...
 	<command>;
 	}
-                                                                                
+
 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
-    <cond2very_very_very_very_very_very_very_very_very_long)
+    <cond2very_very_very_very_very_very_very_very_very_long>)
     <the_only_command>;
 
 switch (<var>)
@@ -88,7 +94,7 @@
 	...
 	<command>;
 	}
-	
+
 
 Functions:
 
@@ -125,7 +131,7 @@
         unary operator '*' and '&' are missing the space from right;
         (and also unary '-').
 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
-    In "function(<var>)" there are no space before '('. 
+    In "function(<var>)" there are no space before '('.
 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if
         it makes your code nicer in being verticaly indented.
 Variables declarations should be followed by a blank line and should always be
@@ -139,4 +145,42 @@
 
 --------------------------------------------------------------------------------
 
-Documentation: use Doxygen
+Documentation:
+
+To document the code use the following rules to allow extraction with doxygen.
+Do not save with comments. Not all comments have to be doxygen comments.
+
+- Use C comments in plain C files and use C++ comments in C++ files for one line
+  comments.
+- Use '/**' (note the two asterisks) to start comments to be extracted by
+  doxygen and start every following line with " *".
+- Use '\' to indicate doxygen keywords/commands (see below).
+- Use the '\deprecated' command to tell if the function is subject to be deleted
+  or to a  complete rewrite.
+
+Example:
+
+To document functions or big structures:
+   /**
+    * \brief This is a short description of the function.
+    *
+    * This function does ...
+    *
+    * \param x1 This is the first parameter named x1
+    * \param y1 This is the second parameter named y1
+    * \return What the function returns
+    *    You can extend that return description (or anything else) by indenting the
+    *    following lines until the next empty line or the next keyword/command.
+    * \see Cross reference
+    */
+
+To document members of a structure that have to be documented (use it at least
+for big structures) use the '/**<' format:
+   int counter; /**< This counter counts images */
+
+For further documentation about doxygen see
+http://www.stack.nl/~dimitri/doxygen/manual.html. For the possible commands you
+can use see http://www.stack.nl/~dimitri/doxygen/commands.html.
+
+But in case just think about that the documentation is for other developers not
+for the end user. So keep the focus.