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.

1 files changed, 34 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