Vale GHA: add comments

.github/workflows/test.yaml

@@ -39,12 +39,18 @@ jobs:
     - name: Get Changed Files
       id: get_changed_files
       uses: jitterbit/get-changed-files@v1
+      # The continue-on-error parameter is set to true as a
+      # workaround for the `head commit is not ahead of base
+      # commit` error that can appear when the PR branch is
+      # out of date.
       continue-on-error: true
       with:
         format: 'json'
     - name: Install more-utils
       run: sudo apt-get install moreutils
     - name: Select Files in Docs Dir
+      # This action filters the list of added and modified
+      # files to only the files that are in the docs/ directory
       id: select_docs_dir_files
       run: |
         docs_dir_files=$(echo $added_modified |  jq -c '[.[] | select(.|test("^docs/"))]')
@@ -55,6 +61,10 @@ jobs:
         added_modified: ${{ steps.get_changed_files.outputs.added_modified }}
     - name: Vale
       uses: errata-ai/[email protected]
+      # Only run the Vale step if the list of added and modified
+      # files inside the docs directory is not empty. If we don't
+      # add this conditional, the Vale step hangs and never
+      # completes when it is passed the empty array.
       if: ${{ '[]' != steps.select_docs_dir_files.outputs.added_modified }}
       with:
         files: '${{ steps.select_docs_dir_files.outputs.added_modified }}'