MAINT: Renamed function "check_version", added documentation.

utils/patch_header.sh

-#
-# ** header v3.0
-# This file is a part of the CaosDB Project.
+# This file is a part of the LinkAhead Project.
 #
 # Copyright (C) 2018 Research Group Biomedical Physics,
 # Max-Planck-Institute for Dynamics and Self-Organization Göttingen
-# Copyright (C) 2019, 2020 Daniel Hornung <d.hornung@indiscale.com>
+# Copyright (C) 2019, 2020, 2025 Daniel Hornung <d.hornung@indiscale.com>
 # Copyright (C) 2020 Henrik tom Wörden <h.tomwoerden@indiscale.com>
-# Copyright (C) 2020 IndiScale <info@indiscale.com>
+# Copyright (C) 2020, 2025 IndiScale <info@indiscale.com>
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License as
@@ -21,12 +19,20 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program. If not, see <https://www.gnu.org/licenses/>.
 #
-# ** end header
-#
 
 ###############################################################################
 #                          header for patch scripts                           #
 ###############################################################################
+#
+# This file defines the following functions (see below for more detailed descriptions):
+#
+# - check_version_or_exit: Check if the stored version is as expected.
+# - update_version: Set the stored version.
+# - dump_table: Store table content into a file.
+# - redo_table: Apply the table content stored by dump_table.
+#
+# This file also sets the `errexit` option (`set -e`).
+#
 
 set -e
 
@@ -63,7 +69,7 @@ configuration make file.  Notable examples are:
 - DATABASE_USER_PW
 
 EOF
-              )
+           )
 
 function _print_help() {
   echo -e "$USAGE"
@@ -115,21 +121,51 @@ done
 if [ -n "$PATCH" ]; then
     echo -ne "applying patch $PATCH to $DATABASE_NAME ... "
 fi
-# @param $1: db version string, e.g. v2.0.0
-# @return: 0 on success, 1 on failure
-function check_version {
+
+# usage: check_version_or_exit version
+#
+# Check if the version string is as expected.  Otherwise, `exit 0`.
+#
+# Arguments
+# ---------
+#
+# version: str
+#   The expected database version string, e.g. 'v2.0.0'
+#
+# Returns
+# -------
+#
+# 0 on success
+function check_version_or_exit {
     local version=$($MYSQL_CMD $(get_db_args) -B -e "Select CaosDBVersion();")
-	  if [[ "$(echo $version | sed 's/^CaosDBVersion()\s//')" = "$1" ]]; then
+    local version="$(echo $version | sed 's/^CaosDBVersion()\s//')"
+	  if [[ "$version" = "$1" ]]; then
         return 0
 	  fi
     uptodate
 }
 
-# @param $1: new version string
+# Deprecated name, call "check_version_or_exit" directly instead.
+function check_version {
+    check_version_or_exit "$1"
+}
+
+# usage: update_version version
+#
+# Set the version string.
+#
+# Arguments
+# ---------
+#
+# version: str
+#   The new database version string, e.g. 'v2.0.0'
 function update_version {
     mysql_execute "DROP FUNCTION IF EXISTS CaosDBVersion; CREATE FUNCTION CaosDBVersion() RETURNS VARCHAR(255) DETERMINISTIC RETURN '$1';"
 }
 
+# usage: dump_table table
+#
+# Dump the table given in the argument into file "caosdb.<table>.<OLD_VERSION>.dump.sql"
 function dump_table {
     if [[ -z $MYSQLDUMP_CMD ]]; then
         echo "Cannot find mysqldump program!" >&2
@@ -139,6 +175,9 @@ function dump_table {
                     > ${DATABASE_NAME}.${1}.${OLD_VERSION}.dump.sql
 }
 
+# usage: redo_table table
+#
+# Apply the dump from `dump_table` to the database.  Takes the same argument.
 function redo_table {
          $MYSQL_CMD $(get_db_args) < ${DATABASE_NAME}.${1}.${OLD_VERSION}.dump.sql
 }