diff --git a/cross/crossdirect/APKBUILD b/cross/crossdirect/APKBUILD
index b4c42dfe5..39c1bc9e8 100644
--- a/cross/crossdirect/APKBUILD
+++ b/cross/crossdirect/APKBUILD
@@ -17,7 +17,7 @@
 
 pkgname=crossdirect
 pkgver=4
-pkgrel=1
+pkgrel=2
 pkgdesc="Wrappers to launch native cross compilers in foreign chroots"
 url="https://postmarketOS.org"
 arch="all"
@@ -77,6 +77,6 @@ package() {
 		install -Dm755 "$srcdir/rustc-$_arch" "$_bindir/rustc"
 	done
 }
-sha512sums="20b963322820de038257304c1eefa85767b78e242eda7459f06d70a1cfae5540a445aa7d5587024bf4d88a4bee28120ef9f5c2d24a648e71b542b9618318deb2  crossdirect.c
+sha512sums="53d2910a9079e1b8a7fef2992eb98ef9e1a70054fa9eb8a00e1c2f2d0b5b0de6fe8f2b8e8f7806396f76b0e97ccbf9169b36215b20f60792c6758f936681730a  crossdirect.c
 6be16ba88720e628a3ecc8fa53f8e7a21d2af268b0509745d989139874d6b94b640bfcff09575eaa19073810be6ef91169c1f83e94f5cf8e6819f2670d9408de  rustc.sh
 ea9bf8db3810d03d0a7395057f3d6e57f7127d87c55deaedc171c255288f5f3cc6fbcc680a5a1b92786cf573875d5dc22521173799fe2639acc97d0715ff905b  rust-qemu-linker.sh"
diff --git a/cross/crossdirect/crossdirect.c b/cross/crossdirect/crossdirect.c
index 46672b4bb..a55e70db3 100644
--- a/cross/crossdirect/crossdirect.c
+++ b/cross/crossdirect/crossdirect.c
@@ -1,4 +1,34 @@
-// HOSTSPEC is defined at compile time, see APKBUILD
+/* Copyright 2020 Zhuowei Zhang, Oliver Smith
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ *
+ * This program gets built to a set of wrapper executables, which launch native
+ * cross compilers inside foreign arch chroots. Speeds up cross compilation a
+ * lot, compared to using just qemu user mode emulation or using the previous
+ * distcc-based methods.
+ *
+ * How this program gets called:
+ * - pmbootstrap creates one native arch chroot and one foreign arch chroot.
+ * - The native chroot gets mounted as /native in the foreign chroot.
+ * - When calling "abuild", pmbootstrap sets PATH to:
+ *   /native/usr/lib/crossdirect/<ARCH>:$PATH
+ * - That crossdirect directory contains a crossdirect-<ARCH> binary built with
+ *   the matching HOSTSPEC (e.g. crossdirect-aarch64 binary with HOSTSPEC
+ *   aarch64-alpine-linux-musl). This binary is symlinked to:
+ *	- <HOSTSPEC>-c++
+ *	- <HOSTSPEC>-cc
+ *	- <HOSTSPEC>-clang
+ *	- <HOSTSPEC>-clang++
+ *	- <HOSTSPEC>-cpp
+ *	- <HOSTSPEC>-g++
+ *	- <HOSTSPEC>-gcc
+ *	- c++
+ *	- cc
+ *	- clang
+ *	- clang++
+ *	- cpp
+ *	- g++
+ *	- gcc
+ */
 
 #include <errno.h>
 #include <libgen.h>
@@ -52,20 +82,26 @@ int main(int argc, char **argv)
 		}
 	}
 
+	// prepend the HOSTSPEC to GCC binaries
 	if (isClang || startsWithHostSpec) {
 		snprintf(newExecutable, sizeof(newExecutable), NATIVE_BIN_DIR "/%s", executableName);
 	} else {
 		snprintf(newExecutable, sizeof(newExecutable), NATIVE_BIN_DIR "/" HOSTSPEC "-%s", executableName);
 	}
 
+	// prepare new arguments for GCC / clang
 	char **newArgsPtr = newargv;
 	*newArgsPtr++ = newExecutable;
 	if (isClang) {
+		// clang does not use a HOSTSPEC prefix for the cross compiler
+		// binary, but instead have a -target argument
 		*newArgsPtr++ = "-target";
 		*newArgsPtr++ = HOSTSPEC;
 	}
 	*newArgsPtr++ = "--sysroot=/";
 
+	// add all arguments passed to this executable to GCC / clang and set
+	// the last arg in newargv to NULL to mark its end
 	memcpy(newArgsPtr, argv + 1, sizeof(char *) * (argc - 1));
 	newArgsPtr += (argc - 1);
 	*newArgsPtr = NULL;
@@ -85,6 +121,7 @@ int main(int argc, char **argv)
 		}
 	}
 
+	// finally exec GCC / clang
 	if (execve(newExecutable, newargv, env) == -1) {
 		fprintf(stderr, "ERROR: crossdirect: failed to execute %s: %s\n", newExecutable, strerror(errno));
 		fprintf(stderr, "Maybe the target arch is missing in the ccache-cross-symlinks package?\n");