[Error Logging](#error-logging)
[GPL header](#gpl-header)
[Git change log](#git-change-log)
-[Sources](#sources)
-[Software Tools](#software-tools)
+[Source Code Style](#source-code-style)
+[External Software Tools](#external-software-tools)
+[Geeqie Software Tools](#geeqie-software-tools)
[Documentation](#documentation)
+[Documentation - C code](#c-code)
+[Documentation - Script files](#script-files)
+[Doxygen](#doxygen)
---
---
-## Sources
+## Source Code Style
Indentation: tabs at 4 spaces
```c
if (<cond>)
- {
- <command>;
- ...
- <command>;
- }
+ {
+ <command>;
+ ...
+ <command>;
+ }
else
- {
- <command>;
- ...
- <command>;
- }
+ {
+ <command>;
+ ...
+ <command>;
+ }
if (<cond_very_very_very_very_very_very_very_very_very_long> &&
<cond2very_very_very_very_very_very_very_very_very_long>)
<the_only_command>;
switch (<var>)
- {
- case 0:
- <command>;
- <command>;
- break;
- case 1:
- <command>; break;
- }
+ {
+ case 0:
+ <command>;
+ <command>;
+ break;
+ case 1:
+ <command>; break;
+ }
for (i = 0; i <= 10; i++)
- {
- <command>;
- ...
- <command>;
- }
+ {
+ <command>;
+ ...
+ <command>;
+ }
```
Functions:
```c
gint bar(<var_def>, <var_def>, <var_def>)
{
- <command>;
- ...
- <command>;
+ <command>;
+ ...
+ <command>;
- return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
+ return 0; // i.e. SUCCESS; if error, you must return minus <err_no> @FIXME
}
void bar2(void)
{
- <command>;
- ...
- <command>;
+ <command>;
+ ...
+ <command>;
}
```
Check if used functions are not deprecated.
---
-## Software Tools
+## External Software Tools
### astyle
A lint-style program may be used, e.g.
```sh
-cppcheck --language=c --library=gtk --enable=all --force -USA_SIGINFO -UZD_EXPORT -Ugettext_noop -DG_KEY_FILE_DESKTOP_GROUP --template=gcc -I. --quiet --suppressions-list=<suppressions file>
+cppcheck --language=c --library=gtk --enable=all --force -USA_SIGINFO -UZD_EXPORT -Ugettext_noop -DG_KEY_FILE_DESKTOP_GROUP --template=gcc -I .. --quiet --suppressions-list=<suppressions file>
```
Where the suppressions file might contain:
unmatchedSuppression
```
-### shellcheck
+### markdownlint
-Shell scripts may also be validated, e.g.
+Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
```sh
-shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
+mdl --style <style file>`
```
-### markdownlint
-
-Markdown documents may be validated with e.g. [markdownlint](https://github.com/markdownlint/markdownlint).
-`mdl --style <style file>`
-
-Where the style file might be:
+Where the style file might contain:
```text
all
+rule 'MD007', :indent => 4
rule 'MD009', :br_spaces => 2
rule 'MD010', :code_blocks => true
exclude_rule 'MD013'
```
+### shellcheck
+
+Shell scripts may also be validated, e.g.
+
+```sh
+shellcheck --enable=add-default-case,avoid-nullary-conditions,check-unassigned-uppercase,deprecate-which,quote-safe-variables
+```
+
### xmllint
The .xml Help files may be validated with e.g. `xmllint`.
-### check-compiles.sh
+---
+
+## Geeqie Software Tools
-This shell script is part of the Geeqie project and will compile Geeqie with various options.
+See the shell scripts section in the Doxygen documentation (`File List`, `detail level 3`, except the `src` sublist).
---
To document the code use the following rules to allow extraction with Doxygen.
Not all comments have to be Doxygen comments.
+### C code
+
- 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 ` *` as shown below.
- Use `@` to indicate Doxygen keywords/commands (see below).
* @FIXME
```
+### Script files
+
+Script files such as .sh, .pl, and .awk should have the file relevant file extension or be symlinked as so.
+
+Doxygen comments should start each line with `##`, and each file should contain:
+
+```sh
+## @file
+## @brief <one line description>
+## <contents description>
+##
+```
+
+## Doxygen
+
For further documentation about Doxygen see the [Doxygen Manual](https://www.doxygen.nl/index.html).
For the possible commands you may use, see [Doxygen Special Commands](https://www.doxygen.nl/manual/commands.html).
The file `./scripts/doxygen-help.sh` may be used to integrate access to the Doxygen files into a code editor.
-The following environment variables may be set to personalize the Doxygen output:
-`DOCDIR=<output folder>`
-`SRCDIR=<the folder above ./src>`
-`PROJECT=`
-`VERSION=`
-`PLANTUML_JAR_PATH=`
-`INLINE_SOURCES=<YES|NO>`
-`STRIP_CODE_COMMENTS=<YES|NO>`
+The following environment variables may be set to personalize the Doxygen output:
+
+```sh
+DOCDIR=<output folder>
+SRCDIR=<the top level directory of the project>
+PROJECT=
+VERSION=
+PLANTUML_JAR_PATH=
+INLINE_SOURCES=<YES|NO>
+STRIP_CODE_COMMENTS=<YES|NO>
+```
Ref: [INLINE\_SOURCES](https://www.doxygen.nl/manual/config.html#cfg_inline_sources)
Ref: [STRIP\_CODE\_COMMENTS](https://www.doxygen.nl/manual/config.html#cfg_strip_code_comments)
-To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
-[The PlantUML jar](https://plantuml.com/download)
-`sudo apt install default-jre`
-`sudo apt install texlive-font-utils`
+For shell scripts to be documented, the file `doxygen-bash.sed` must be in the `$PATH` environment variable.
+It can be download from here:
+
+```sh
+wget https://raw.githubusercontent.com/Anvil/bash-doxygen/master/doxygen-bash.sed
+chmod +x doxygen-bash.sed
+```
+
+To include diagrams in the Doxygen output, the following are required to be installed. The installation process will vary between distributions:
+
+[The PlantUML jar](https://plantuml.com/download)
+
+```sh
+sudo apt install default-jre
+sudo apt install texlive-font-utils
+```
---