1 [Log Window](#log-window)
2 [GPL header](#gpl-header)
3 [Git change log](#git-change-log)
5 [Documentation](#documentation)
10 # <a name='log-window'>
14 Use `DEBUG_0()` only for temporary debugging i.e. not in code in the repository.
15 The user will then not see irrelevant debug output when the default
16 `debug level = 0` is used.
19 If the first word of the message is "error" or "warning" (case insensitive) the message will be color-coded appropriately.
23 For use with the [GTKInspector](https://wiki.gnome.org/action/show/Projects/GTK/Inspector?action=show&redirect=Projects%2FGTK%2B%2FInspector) to provide a visual indication of where objects are declared.
25 Sample command line call:
26 `GTK_DEBUG=interactive src/geeqie`
28 --------------------------------------------------------------------------------
30 # <a name='gpl-header'>
33 Include a header in every file, like this:
36 * @brief Short description of this file.
40 * Optionally detailed description of this file
45 * This file is a part of Geeqie project (http://www.geeqie.org/).
46 * Copyright (C) 2008 - 2021 The Geeqie Team
48 * This program is free software; you can redistribute it and/or modify it
49 * under the terms of the GNU General Public License as published by the Free
50 * Software Foundation; either version 2 of the License, or (at your option)
53 * This program is distributed in the hope that it will be useful, but WITHOUT
54 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
55 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
61 # <a name='git-change-log'>
64 If referencing a Geeqie GitHub issue, include the issue number in the summary line. Start with a short summary in the first line (without a dot at the end) followed by a empty line.
66 If referencing a Geeqie GitHub issue, include a hyperlink to the GitHub issue webpage in the message body. Use whole sentences beginning with Capital letter. For each modification use a new line. Or you can write the theme, colon and then every change on new line, begin with "- ".
68 See also [A Note About Git Commit Messages](http://www.tpope.net/node/106)
74 `There was the bug that something was wrong. I fixed it.`
77 `- the interface was modified`
78 `- new functions were added`
80 Also please use your full name and a working e-mail address as author for any contribution.
82 --------------------------------------------------------------------------------
87 Indentation: tabs at 4 spaces
92 - of variables & functions: small\_letters
93 - of defines: CAPITAL\_LETTERS
95 Try to use explicit variable and function names.
96 Try not to use macros.
97 Use EITHER "struct foo" OR "foo"; never both
115 if (<cond_very_very_very_very_very_very_very_very_very_long> &&
116 <cond2very_very_very_very_very_very_very_very_very_long>)
129 for (i = 0; i <= 10; i++)
138 gint bar(<var_def>, <var_def>, <var_def>)
144 return 0; // i.e. SUCCESS; if error, you must return minus <err_no>
154 Pragma: (Indentation 2 spaces)
158 # define _(String) (String)
159 #endif /* ENABLE_NLS */
166 Use spaces around every operator (except ".", "->", "++" and "--").
167 Unary operator '*' and '&' are missing the space from right, (and also unary '-').
169 As you can see above, parentheses are closed to inside, i.e. " (blah blah) "
170 In "`function(<var>)`" there is no space before the '('.
171 You MAY use more tabs/spaces than you OUGHT TO (according to this CodingStyle), if it makes your code nicer in being vertically indented.
172 Variables declarations should be followed by a blank line and should always be at the start of the block.
175 Use glib types when possible (ie. gint and gchar instead of int and char).
176 Use glib functions when possible (ie. `g_ascii_isspace()` instead of `isspace()`).
177 Check if used functions are not deprecated.
179 --------------------------------------------------------------------------------
181 # <a name='documentation'>
184 Use American, rather than British English, spelling. This will facilitate consistent
185 text searches. User text may be translated via the en_GB.po file.
187 To document the code use the following rules to allow extraction with doxygen.
188 Do not save with comments. Not all comments have to be doxygen comments.
190 - Use C comments in plain C files and use C++ comments in C++ files for one line
192 - Use '/**' (note the two asterisks) to start comments to be extracted by
193 doxygen and start every following line with " *".
194 - Use '@' to indicate doxygen keywords/commands (see below).
195 - Use the '@deprecated' command to tell if the function is subject to be deleted
196 or to a complete rewrite.
200 To document functions or big structures:
203 * @brief This is a short description of the function.
205 * This function does ...
207 * @param x1 This is the first parameter named x1
208 * @param y1 This is the second parameter named y1
209 * @return What the function returns
210 * You can extend that return description (or anything else) by indenting the
211 * following lines until the next empty line or the next keyword/command.
212 * @see Cross reference
215 To document members of a structure that have to be documented (use it at least
216 for big structures) use the `/**<` format:
217 `int counter; /**< This counter counts images */`
219 Document TODO or FIXME comments as:
229 For further documentation about doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
230 For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
232 The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
234 The following environment variables may be set to personalize the Doxygen output:
235 `DOCDIR=<output folder>`
236 `SRCDIR=<the folder above ./src>`
240 `INLINE_SOURCES=<YES|NO>`
241 `STRIP_CODE_COMMENTS=<YES|NO>`
243 Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
244 Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
246 To include diagrams (if any) in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
247 [The PlantUML jar](https://plantuml.com/download)
248 `sudo apt install default-jre`
249 `sudo apt install texlive-font-utils`
253 But in case just think about that the documentation is for other developers not
254 for the end user. So keep the focus.