add comments

hack/update-bazel.sh

@@ -29,9 +29,11 @@ go install k8s.io/kubernetes/vendor/github.com/bazelbuild/bazel-gazelle/cmd/gaze
 go install k8s.io/kubernetes/vendor/github.com/bazelbuild/buildtools/buildozer
 go install k8s.io/kubernetes/vendor/k8s.io/repo-infra/kazel
 
+# Find all of the staging repos.
 while IFS='' read -r repo; do staging_repos+=("${repo}"); done <\
   <(cd "${KUBE_ROOT}/staging/src" && find k8s.io/ -mindepth 1 -maxdepth 1 -type d | LANG=C sort)
 
+# Save the staging repos into a Starlark list that can be used by Bazel rules.
 (
   cat "${KUBE_ROOT}/hack/boilerplate/boilerplate.generatebzl.txt"
   echo "# This file is autogenerated by hack/update-bazel.sh."
@@ -45,16 +47,27 @@ while IFS='' read -r repo; do staging_repos+=("${repo}"); done <\
   echo "]"
 ) >"${KUBE_ROOT}/staging/repos_generated.bzl"
 
+# Ensure there's a BUILD file at vendor/ so the all-srcs rule in the root
+# BUILD.bazel file is isolated from changes under vendor/.
 touch "${KUBE_ROOT}/vendor/BUILD"
+# Ensure there's a BUILD file at the root of each staging repo. This prevents
+# the package-srcs glob in vendor/BUILD from following the symlinks
+# from vendor/k8s.io into staging. Following these symlinks through
+# vendor results in files being excluded from the kubernetes-src tarball
+# generated by Bazel.
 for repo in "${staging_repos[@]}"; do
   touch "${KUBE_ROOT}/staging/src/${repo}/BUILD"
 done
+
+# Run gazelle to update Go rules in BUILD files.
 gazelle fix \
     -external=vendored \
     -mode=fix \
     -repo_root "${KUBE_ROOT}" \
     "${KUBE_ROOT}"
 
+# Run kazel to update the pkg-srcs and all-srcs rules as well as handle
+# Kubernetes code generators.
 kazel
 
 # make targets in vendor manual