Mercurial > geeqie.yaz
changeset 1640:ab5945017b4a
Update documentation
Now it holds a more verbose doxygen description as discussed in mailing
list.
- Doxygen style description
- Small visibility changes
- Commit message change
| author | mow |
|---|---|
| date | Sat, 13 Jun 2009 22:19:57 +0000 |
| parents | 56115e934133 |
| children | 34c71cbbbd26 |
| files | CODING HACKING po/README |
| diffstat | 3 files changed, 85 insertions(+), 42 deletions(-) [+] |
line wrap: on
line diff
--- 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.
--- 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.
--- 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: