From fc42feeca49aa42acc28e7a4bd3e43347139b1a5 Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@sbcglobal.net>
Date: Sun, 24 May 2015 00:21:00 -0600
Subject: 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.
---
 src/xbs-abslibre/helper-abslibre | 34 ++++++++++++++++++++++++++++++++++
 src/xbs/xbs                      |  4 ++++
 2 files changed, 38 insertions(+)

(limited to 'src')

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 "$@"
-- 
cgit v1.2.3