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" \

.github/workflows/scheduled.yaml

@@ -45,6 +45,15 @@ jobs:
         run: |
           : Remove Stale Ccache Caches
 
+          # The jq expressions below use multiple 'select' calls to filter
+          # each item in the array with the 'actions_caches' key.
+          # First it only selects objects whose 'ref' element has the value
+          # 'refs/heads/master', of those objects only those whose 'key'
+          # value matches the specifies expression, before finally only
+          # selecting the 'id' and 'key' elements for a new object.
+          # The final 'join' command combines both elements with a semicolon
+          # into a raw string which can then be parsed directly.
+
           echo '::group::Processing master branch cache entries'
           while IFS=";" read -r cache_id cache_name; do
             if [[ "${cache_name}" ]]; then
@@ -114,6 +123,17 @@ jobs:
           : Check Nightly Runs ☑️
           if [[ "${RUNNER_DEBUG}" ]]; then set -x; fi
 
+          # This 'gh' command retrieves the last 2 runs of the workflow defined
+          # by 'scheduled.yaml' and retrieve only the 'headSha' value of the
+          # JSON response payload.
+          #
+          # As this job runs in context of the same workflow, the first element
+          # of the workflow list will be the currently active run.
+          #
+          # The jq expression then selects the 'headSha' element of the second
+          # element in the array, which is the SHA-1 hash of the commit used
+          # for the immediately prior run of this workflow.
+
           last_nightly=$(gh run list --workflow scheduled.yaml --limit 2 --json headSha --jq '.[1].headSha')
 
           if [[ "${GITHUB_SHA}" == "${last_nightly}" ]]; then
@@ -157,6 +177,17 @@ jobs:
           : Check Nightly Runs ☑️
           if (( ${+RUNNER_DEBUG} )) setopt XTRACE
 
+          # This 'gh' command retrieves the last 2 runs of the workflow defined
+          # by 'scheduled.yaml' and retrieve only the 'headSha' value of the
+          # JSON response payload.
+          #
+          # As this job runs in context of the same workflow, the first element
+          # of the workflow list will be the currently active run.
+          #
+          # The jq expression then selects the 'headSha' element of the second
+          # element in the array, which is the SHA-1 hash of the commit used
+          # for the immediately prior run of this workflow.
+
           local last_nightly=$(gh run list --workflow scheduled.yaml --limit 2 --json headSha --jq '.[1].headSha')
 
           if [[ "${GITHUB_SHA}" == "${last_nightly}" ]] {