chore(pipeline): more descriptive comments

Author: thekaveman

.github/bin/repos/filter.sh

@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 set -eu
 
+# reads repository JSON text from stdin
 # remove archived repositories, and the reference to this repository
+# print resulting JSON text to stdout
 
 cat | jq '[.[] | select(.archived==false) | select(.name!="cal-itp.github.io")]'

.github/bin/repos/get.sh

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
 set -eu
 
+# print public Cal-ITP source repositories as JSON text to stdout
+# see https://docs.github.com/en/rest/reference/repos#list-organization-repositories
+
 curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/orgs/cal-itp/repos?type=source

.github/bin/repos/pipeline.sh

@@ -1,9 +1,14 @@
 #!/usr/bin/env bash
 set -eu
 
+# run the repository data pipeline: get > filter > sort > output
+
 source=.github/bin/repos
 target=_data/repos.json
 
 $source/get.sh | $source/filter.sh | $source/sort.sh > "$target"
 
+# save resulting file name in GitHub Actions context
+# see https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter
+
 echo "::set-output name=data_file::$target"

.github/bin/repos/sort.sh

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
 set -eu
 
+# reads repository JSON text from stdin
+# sort by lowercase name
+# print resulting JSON text to stdout
+
 cat | jq "sort_by(.name | ascii_downcase)"