Add comments to XBS stuff so that I can understand it drunk.

Or really at all having not had memory of writing it, as most of that was
about a year ago and I didn't write any comments and barely any
documentation.  But it's funnier if I mention that I've had a couple
drinks.

2 files changed, 38 insertions, 0 deletions

diff --git a/src/xbs-abslibre/helper-abslibre b/src/xbs-abslibre/helper-abslibre
index 4af88b1..8bca72e 100755
--- a/src/xbs-abslibre/helper-abslibre
+++ b/src/xbs-abslibre/helper-abslibre
@@ -36,16 +36,38 @@ conf() {
 
 ################################################################################
 
+# Operates on the `abslibre` format[0].  On the client/developer side,
+# release-client *copies* files from the `abslibre` tree to an
+# `abstree`[1] tree located at `devbox:${ABSLIBREDEST}/${arch}`.  On
+# the server side, after those `abstree`s have been uploaded
+# (ssh/rsync), release-server *moves* them out of the `abstree` into a
+# different `abslibre` on the server, similarly located at
+# `repobox:${ABSLIBREDEST}/${arch}`.
+#
+# [0]: https://projects.parabola.nu/packages/pbs-tools.git/tree/docs/format-abslibre.md
+# [1]: https://projects.parabola.nu/packages/pbs-tools.git/tree/docs/format-abstree.md
+
+# The number of arguments and CWD constraints are enforced by the main
+# XBS program, no need to check those things here!
+
+# Args: none
+# CWD: a directory with a PKGBUILD, in an 'abslibre' tree.
 status() {
 	[[ -z $(git status -s .) ]]
 }
 
+# Args: none
+# CWD: anywhere
+# Host: developer box
 download() {
 	conf WORKDIR ABSLIBRERECV ABSLIBRESEND
 
 	gitget -f -p "$ABSLIBRESEND" checkout "$ABSLIBRERECV" "$WORKDIR/abslibre" || return 1
 }
 
+# Args: REPO ARCH
+# CWD: a directory with a PKGBUILD, in an 'abslibre' tree.
+# Host: developer box
 release-client() {
 	local repo=$1
 	local arch=$2
@@ -63,6 +85,9 @@ release-client() {
 	git ls-files -z | xargs -0 -I{} cp -- {} "$pkgdir"
 }
 
+# Args: REPO ARCH
+# CWD: a directory with a PKGBUILD, outside of ${ABSLIBREDEST}
+# Host: repo
 release-server() {
 	local repo=$1
 	local repo=$2
@@ -86,6 +111,9 @@ release-server() {
 	fi
 }
 
+# Args: PKGBASE REPO ARCH
+# CWD: anywhere
+# Host: repo
 unrelease() {
 	local pkgbase=$1
 	local repo=$2
@@ -106,6 +134,9 @@ unrelease() {
 	fi
 }
 
+# Args: FROMREPO TOREPO PKGBASE
+# CWD: anywhere
+# Host: repo
 move() {
 	local repo_from=$1
 	local repo_to=$2
@@ -139,6 +170,9 @@ move() {
 	done
 }
 
+# Args: PKGBASE REPO ARCH
+# CWD: anywhere
+# Host: repo
 releasepath() {
 	local pkgbase=$1
 	local repo=$2
diff --git a/src/xbs/xbs b/src/xbs/xbs
index 131dee9..8bd3bdf 100755
--- a/src/xbs/xbs
+++ b/src/xbs/xbs
@@ -70,6 +70,10 @@ usage() {
 status() {
 	if [[ ! -f PKGBUILD ]]; then
 		error 'PKGBUILD not found'
+		# Though in this file in general it doesn't matter, in
+		# this case it does: Using "exit" instead of "return"
+		# is imporant because it prevents flow returning to
+		# release-client.
 		exit 1
 	fi
 	"$HELPER" status "$@"