CI: Add documentation to complex shell script constructs

.github/actions/check-changes/action.yaml

@@ -45,6 +45,11 @@ runs:
         shopt -s extglob
         shopt -s dotglob
 
+        # 4b825dc642cb6eb9a060e54bf8d69288fbee4904 is a "hidden" sha1 hash of
+        # the "empty tree", retrived via 'git hash-object -t tree /dev/null',
+        # and used here as a last-resort fallback to always provide a valid
+        # git ref.
+
         if [[ "${GIT_BASE_REF}" ]]; then
           if ! git cat-file -e "${GIT_BASE_REF}" &> /dev/null; then
             echo "::warning::Provided base reference ${GIT_BASE_REF} is invalid"

.github/actions/generate-docs/action.yaml

@@ -23,12 +23,25 @@ runs:
         : "${minor:=}"
         : "${patch:=}"
 
+        # This expression will first try to match all the LIBOBS_API_[...]_VER
+        # lines in 'obs-config.h', before removing the '#define ' prefix and
+        # trimming away whitespace characters and linebreaks.
+        # This will yield a single line with the each major, minor, and patch
+        # version variable name followed by its value, so every even item
+        # in this string will contain a version part.
+
         read -r _ major _ minor _ patch _ <<< \
           "$(grep -E -e "#define LIBOBS_API_(MAJOR|MINOR|PATCH)_VER *" libobs/obs-config.h \
             | sed 's/#define //g' \
             | tr -s ' ' \
             | tr '\n' ' ')"
 
+        # This expression simply replaces the definition of the 'version' and
+        # 'release' variables in the Python script with updated variants using
+        # the version tokens set by the previous expression.
+        # The copyright variable assignment is updated to use the current
+        # local year as the second year value.
+
         sed -i -E \
           -e "s/version = '([0-9]+\.[0-9]+\.[0-9]+)'/version = '${major}.${minor}.${patch}'/g" \
           -e "s/release = '([0-9]+\.[0-9]+\.[0-9]+)'/release = '${major}.${minor}.${patch}'/g" \

.github/actions/sparkle-appcast/action.yaml

@@ -110,6 +110,23 @@ runs:
         hdiutil detach ${mount_point}
 
         curl -s -L -O ${feed_url}
+
+        # The Xpath Xplained:
+        #
+        # //rss/channel/item              - Select every <item> node, under a
+        #                                   <channel> node, under a <rss> node,
+        #                                   which:
+        # [*...]                          - Has a child node, which
+        # [local-name()='channel']        - Has the local name "channel"
+        #                                   (required to match the
+        #                                   namespaced sparkle:channel node),
+        #                                   which in turn has
+        # [text()='${{ inputs.channel}']  - A text node that contains the
+        #                                   content of inputs.channel
+        # /enclosure/@url                 - Then select the "url" attribute of
+        #                                   every <enclosure> node under
+        #                                   these matching <item> nodes
+
         local -a artifacts=($(\
           xmllint \
             -xpath "//rss/channel/item[*[local-name()='channel'][text()='${{ inputs.channel }}']]/enclosure/@url" \