mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-02 06:55:16 +00:00
Code Issues Releases Wiki Activity

[#1610] improvements to doxygen on shell scripts

Browse Source
This commit is contained in:
Andrei Pavel
2020-12-23 14:19:42 +02:00
parent 55b7bad7a2
commit 7e71c1a19d
2 changed files with 10 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/devel/mainpage.dox
View File

@@ -42,7 +42,7 @@
* - @subpage unitTestsSanitizers * - @subpage unitTestsSanitizers
* - @subpage unitTestsDatabaseConfig * - @subpage unitTestsDatabaseConfig
* - @subpage unitTestsSysrepo * - @subpage unitTestsSysrepo
* - @subpage writingShellTests * - @subpage writingShellScriptsAndTests
* *
* @section performance Performance * @section performance Performance
* - @subpage benchmarks * - @subpage benchmarks

15
doc/devel/unit-tests.dox
View File

@@ -353,7 +353,7 @@ local all postgres trust
Use HELP for help. Use HELP for help.
cqlsh> @endverbatim\n cqlsh> @endverbatim\n
@section writingShellTests Writing shell tests @section writingShellScriptsAndTests Writing shell scripts and tests
Shell tests are `shellcheck`ed. But there are other writing practices that are Shell tests are `shellcheck`ed. But there are other writing practices that are
good to follow in order to keep, not only shell tests, but shell scripts in good to follow in order to keep, not only shell tests, but shell scripts in
@@ -369,13 +369,13 @@ the primordial non-GNU sh, Ubuntu which links it to dash. These four shells
should all be tested against, when adding shell scripts or making changes to should all be tested against, when adding shell scripts or making changes to
them. them.
- Reference variables with accolades. - Reference variables with curly brackets.
@code @code
${var} # better ${var} # better
$var $var
@endcode @endcode
For consistency with cases where you need advanced features from the variables For consistency with cases where you need advanced features from the variables
which make the accolades mandatory. Such cases are: which make the curly brackets mandatory. Such cases are:
@code @code
# Retrieving variable/string length... # Retrieving variable/string length...
${#var} ${#var}
@@ -385,6 +385,9 @@ ${var-default}
# Substituting the variable with a given value when the variable is defined... # Substituting the variable with a given value when the variable is defined...
${var+value} ${var+value}
# Concatenating the value of a variable with an alphanumeric constant...
${var}constant
@endcode @endcode
- Always use `printf` instead of `echo`. There are times when a newline is not - Always use `printf` instead of `echo`. There are times when a newline is not
@@ -408,7 +411,7 @@ echo "${var1}something${var2}" | wc -c
# SC2039: In POSIX sh, echo flags are undefined. # SC2039: In POSIX sh, echo flags are undefined.
echo -n "${var1}something${var2}" | wc -c echo -n "${var1}something${var2}" | wc -c
# Result: # Result:
32 # sometimes 32 # sometimes, other times an error
@endcode @endcode
`printf` also has the benefit of separating the format from the actual variables `printf` also has the benefit of separating the format from the actual variables
which has many use cases. One such use case is coloring output with ANSI escape which has many use cases. One such use case is coloring output with ANSI escape
@@ -515,7 +518,7 @@ hostname=$(cat /etc/hostname)
# Nested executions # Nested executions
is_ssh_open=$(nc -vz $(cat /etc/hostname).lab.isc.org 22) is_ssh_open=$(nc -vz $(cat /etc/hostname).lab.isc.org 22)
# Results in "command not found" messages. # Results in confusing "command not found" messages.
is_ssh_open=`nc -vz `cat /etc/hostname`.lab.isc.org 22` is_ssh_open=`nc -vz `cat /etc/hostname`.lab.isc.org 22`
@endcode @endcode
@@ -543,7 +546,7 @@ do-something --some --other --optional --parameters "${parameters[@]}"
do-something --some --other --optional --parameters "${@}" do-something --some --other --optional --parameters "${@}"
@endcode @endcode
- Never use `eval`. They don't preserve original quoting. Have faith that there - Never use `eval`. It doesn't preserve original quoting. Have faith that there
are always good alternatives. are always good alternatives.
*/ */