# HG changeset patch
# User mow
# Date 1244931597 0
# Node ID b9a9a457860dabefb12556fa36593776d6a098cf
# Parent  b8235f919d6b99324252a947b69dc05ce1dffb75
Update documentation

Now it holds a more verbose doxygen description as discussed in mailing
list.

- Doxygen style description
- Small visibility changes
- Commit message change

diff -r b8235f919d6b -r b9a9a457860d CODING
--- 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.
diff -r b8235f919d6b -r b9a9a457860d HACKING
--- a/HACKING	Sat Jun 13 19:26:32 2009 +0000
+++ b/HACKING	Sat Jun 13 22:19:57 2009 +0000
@@ -1,17 +1,17 @@
 A brief overview for those that wish to work with the source.
 
-The Makefiles and configure script are generated by the autogen.sh script, usually
-only distributed with snapshot releases. Running autogen.sh requires automake
-and autoconf. GNU gettext may also be needed by autogen.sh.
+The Makefiles and configure script are generated by the autogen.sh script,
+usually only distributed with snapshot releases. Running autogen.sh requires
+automake and autoconf. GNU gettext may also be needed by autogen.sh.
 
-SVN commits _require_ an explicit log message. Think it will be used in the release
-Changelog.
+SVN commits _require_ an explicit log message. Think it will be used in the
+release Changelog.
 
 Coders should respect general coding style (see CODING).
 
 Coders, please resync po/POTFILES.in if you add or remove source files from src/
-directory (using regen_potfiles.sh script in po/) and re-run make update-po 
-when appropriate to keep translations in sync with the code.
+directory (using regen_potfiles.sh script in po/) and re-run make update-po when
+appropriate to keep translations in sync with the code.
 
 Maintainers, don't forget to run make update-po before releases.
 
diff -r b8235f919d6b -r b9a9a457860d po/README
--- a/po/README	Sat Jun 13 19:26:32 2009 +0000
+++ b/po/README	Sat Jun 13 22:19:57 2009 +0000
@@ -1,15 +1,14 @@
 Translators create a translation by creating the appropriate .po file in the /po
 directory. Please see the gettext info pages for an overview and instructions.
 Basically: Add your language code to the   ALL_LINGUAS=   line in configure.in,
-then get started translating the strings in your ??.po file.
-Note: The strings for debug output is intentionally not marked for translation.
-
-To update a specific translation, one may use make update-po PO=[lang]  (ie. make update-po PO=fr).
+then get started translating the strings in your ??.po file. Note: The strings
+for debug output is intentionally not marked for translation.
 
-To update all translation files, use make update-po.
-You should only use it when needed (before a release or when there were many
-changes in source code).
+To update a specific translation, one may use make update-po PO=[lang]  (ie.
+make update-po PO=fr).
 
+To update all translation files, use make update-po. You should only use it when
+needed (before a release or when there were many changes in source code).
 
 
 Helper scripts: