calculate-cache.sh: add descriptions and output examples to functions

Signed-off-by: Norio Nomura <[email protected]>

Author: norio-nomura

hack/calculate-cache.sh

@@ -24,6 +24,25 @@ LIMA_HOME=$(mktemp -d)
 export LIMA_HOME
 
 # parse the workflow file and print runs-on and template
+# e.g.
+# ```console
+# $ print_runs_on_template_from_workflow .github/workflows/test.yml
+# macos-12        templates/default.yaml
+# ubuntu-24.04    templates/alpine.yaml
+# ubuntu-24.04    templates/debian.yaml
+# ubuntu-24.04    templates/fedora.yaml
+# ubuntu-24.04    templates/archlinux.yaml
+# ubuntu-24.04    templates/opensuse.yaml
+# ubuntu-24.04    templates/experimental/net-user-v2.yaml
+# ubuntu-24.04    templates/experimental/9p.yaml
+# ubuntu-24.04    templates/docker.yaml
+# ubuntu-24.04    templates/../hack/test-templates/alpine-9p-writable.yaml
+# ubuntu-24.04    templates/../hack/test-templates/test-misc.yaml
+# macos-12        templates/vmnet.yaml
+# macos-12        https://raw.githubusercontent.com/lima-vm/lima/v0.15.1/examples/ubuntu-lts.yaml
+# macos-13        templates/experimental/vz.yaml
+# macos-13        templates/fedora.yaml
+# ```
 function print_runs_on_template_from_workflow() {
 	yq -o=j "$1" | jq -r '
 		"./.github/actions/setup_cache_for_template" as $action |
@@ -48,6 +67,14 @@ function print_runs_on_template_from_workflow() {
 	'
 }
 
+# returns the OS name from the runner equivalent to the expression `${{ runner.os }}` in the workflow
+# e.g.
+# ```console
+# $ runner_os_from_runner "macos-12"
+# macOS
+# $ runner_os_from_runner "ubuntu-24.04"
+# Linux
+# ```
 function runner_os_from_runner() {
 	# shellcheck disable=SC2249
 	case "$1" in
@@ -60,6 +87,13 @@ function runner_os_from_runner() {
 	esac
 }
 
+# check the remote location and return the http code and size.
+# The result is cached in .calculate-cache-response-cache.yaml
+# e.g.
+# ```console
+# $ check_location "https://cloud-images.ubuntu.com/releases/24.04/release-20240725/ubuntu-24.04-server-cloudimg-amd64.img"
+# 200 585498624
+# ```
 function check_location() {
 	location="$1"
 	readonly cache_file="./.calculate-cache-response-cache.yaml"
@@ -74,6 +108,12 @@ function check_location() {
 	echo "${http_code_and_size}"
 }
 
+# print image location, digest, size, hash, containerd, containerd_location, containerd_digest, containerd_size from the template
+# e.g.
+# ```console
+# $ print_location_digest_size_hash_from_template "templates/default.yaml"
+# https://cloud-images.ubuntu.com/releases/24.04/release-20240725/ubuntu-24.04-server-cloudimg-amd64.img sha256:d2377667ea95222330ca2287817403c85178dad397e9fed768a9b4aec79d2a7f 585498624 49aa50a4872ded07ebf657c0eaf9e44ecc0c174d033a97c537ecd270f35b462f true https://github.com/containerd/nerdctl/releases/download/v1.7.6/nerdctl-full-1.7.6-linux-amd64.tar.gz sha256:2c841e097fcfb5a1760bd354b3778cb695b44cd01f9f271c17507dc4a0b25606 237465717
+# ```
 function print_location_digest_size_hash_from_template() {
 	readonly template=$1
 	case "${template}" in
@@ -124,6 +164,11 @@ function print_location_digest_size_hash_from_template() {
 }
 
 # format first column to MiB
+# e.g.
+# ```console
+# $ echo 585498624 | size_to_mib
+#   558.38 MiB
+# ```
 function size_to_mib() {
 	awk '
 		function mib(size) { return sprintf("%7.2f MiB", size / 1024 / 1024) }
@@ -135,6 +180,36 @@ function size_to_mib() {
 }
 
 # actual_cache_sizes=$(gh cache list --json key,createdAt,sizeInBytes|jq '[.[]|{"key":.key,"value":.sizeInBytes}]|from_entries')
+# e.g.
+# ```console
+# $ echo "${actual_cache_sizes}"
+# {
+#   "Linux-1c3b2791d52735d916dc44767c745c2319eb7cae74af71bbf45ddb268f42fc1d": 810758533,
+#   "Linux-231c66957fc2cdb18ea10e63f60770049026e29051ecd6598fc390b60d6a4fa6": 633036717,
+#   "Linux-3b906d46fa532e3bc348c35fc8e7ede6c69f0b27032046ee2cbb56d4022d1146": 574242367,
+#   "Linux-69a547b760dbf1650007ed541408474237bc611704077214adcac292de556444": 70310855,
+#   "Linux-7782f8b4ff8cd378377eb79f8d61c9559b94bbd0c11d19eb380ee7bda19af04e": 494141177,
+#   "Linux-8812aedfe81b4456d421645928b493b1f2f88aff04b7f3171207492fd44cd189": 812730766,
+#   "Linux-caa7d8af214d55ad8902e82d5918e61573f3d6795d2b5ad9a35305e26fa0e6a9": 754723892,
+#   "Linux-colima-v0.6.5": 226350335,
+#   "Linux-de83bce0608d787e3c68c7a31c5fab2b6d054320fd7bf633a031845e2ee03414": 810691197,
+#   "Linux-eb88a19dfcf2fb98278e7c7e941c143737c6d7cd8950a88f58e04b4ee7cef1bc": 570625794,
+#   "Linux-f88f0b3b678ff6432386a42bdd27661133c84a36ad29f393da407c871b0143eb": 68490954,
+#   "golangci-lint.cache-Linux-2850-74615231540133417fd618c72e37be92c5d3b3ad": 2434144,
+#   "macOS-231c66957fc2cdb18ea10e63f60770049026e29051ecd6598fc390b60d6a4fa6": 633020464,
+#   "macOS-49aa50a4872ded07ebf657c0eaf9e44ecc0c174d033a97c537ecd270f35b462f": 813179462,
+#   "macOS-8f37f663956af5f743f0f99ab973729b6a02f200ebfac7a3a036eff296550732": 810756770,
+#   "macOS-ef5509b5d4495c8c3590442ee912ad1c9a33f872dc4a29421c524fc1e2103b59": 813179476,
+#   "macOS-upgrade-v0.15.1": 1157814690,
+#   "setup-go-Linux-ubuntu20-go-1.23.0-02756877dbcc9669bb904e42e894c63aa9801138db94426a90a2d554f2705c52": 1015518352,
+#   "setup-go-Linux-ubuntu20-go-1.23.0-6bce2eefc6111ace836de8bb322432c072805737d5f3c5a3d47d2207a05f50df": 936433302,
+#   "setup-go-Linux-ubuntu24-go-1.22.6-02756877dbcc9669bb904e42e894c63aa9801138db94426a90a2d554f2705c52": 1090001859,
+#   "setup-go-Linux-ubuntu24-go-1.23.0-02756877dbcc9669bb904e42e894c63aa9801138db94426a90a2d554f2705c52": 526146768,
+#   "setup-go-Windows-go-1.23.0-02756877dbcc9669bb904e42e894c63aa9801138db94426a90a2d554f2705c52": 1155374040,
+#   "setup-go-Windows-go-1.23.0-6bce2eefc6111ace836de8bb322432c072805737d5f3c5a3d47d2207a05f50df": 1056433137,
+#   "setup-go-macOS-go-1.23.0-02756877dbcc9669bb904e42e894c63aa9801138db94426a90a2d554f2705c52": 1060919942,
+#   "setup-go-macOS-go-1.23.0-6bce2eefc6111ace836de8bb322432c072805737d5f3c5a3d47d2207a05f50df": 982139209
+# }
 actual_cache_sizes=$(
 	gh cache list --json key,createdAt,sizeInBytes |
 		jq 'sort_by(.createdAt)|reverse|unique_by(.key)|sort_by(.key)|map({"key":.key,"value":.sizeInBytes})|from_entries'