From 7fddcb83606f38038d20acc22964917733faf511 Mon Sep 17 00:00:00 2001
From: nkraetzschmar <9020053+nkraetzschmar@users.noreply.github.com>
Date: Mon, 16 Sep 2024 09:08:22 +0200
Subject: [PATCH] document part of builder make util scripts

---
 builder/make_get_artifact_rules     | 2 ++
 builder/make_get_image_dependencies | 6 ++++++
 builder/make_list_build_artifacts   | 2 ++
 3 files changed, 10 insertions(+)

diff --git a/builder/make_get_artifact_rules b/builder/make_get_artifact_rules
index c38ffb8..6ebe4ad 100755
--- a/builder/make_get_artifact_rules
+++ b/builder/make_get_artifact_rules
@@ -7,6 +7,8 @@ extensions=(release manifest raw)
 
 for feature in "features/"*; do
 	for i in "$feature/"{image,convert}.*; do
+		# get target artifact file extensions, usually this is the image/convert script extension
+		# except if the script extension is of the form filename.extA~extB in which case the artifact extension is .extA only
 		extension="$(grep -E -o '(\.[a-z][a-zA-Z0-9\-_~]*)*$' <<< "$i")"
 		real_extension="${extension%~*}"
 		extensions+=("${real_extension:1}")
diff --git a/builder/make_get_image_dependencies b/builder/make_get_image_dependencies
index 20c4935..f1a98b3 100755
--- a/builder/make_get_image_dependencies
+++ b/builder/make_get_image_dependencies
@@ -55,6 +55,12 @@ for feature in "${features[@]}"; do
 	advanced_convert_scripts=("features/$feature/convert${extension:-.raw}~"*)
 	set -f
 
+	# Advanced convert scripts are scripts of the form convert.extA~extB.
+	# Unlike regular convert scripts these don't always get the image.raw as input,
+	# instead they recieve image.extB as their input.
+	# This allows for convert scripts to operate on image scripts producing non .raw output
+	# or for covert scripts to operate on outputs of prior convert scripts.
+
 	for i in "${advanced_convert_scripts[@]}"; do
 		if [ "$is_feature_script" = 1 ]; then
 			printf "error: %s conflicts with %s\n" "$script" "$i"
diff --git a/builder/make_list_build_artifacts b/builder/make_list_build_artifacts
index 553282d..99f684a 100755
--- a/builder/make_list_build_artifacts
+++ b/builder/make_list_build_artifacts
@@ -11,6 +11,8 @@ artifacts=(".build/$cname-$COMMIT.tar" ".build/$cname-$COMMIT.release" ".build/$
 
 for feature in "${features[@]}"; do
 	for i in "features/$feature/"{image,convert}.*; do
+		# get target artifact file extension, usually this is the image/convert script extension
+		# except if the script extension is of the form filename.extA~extB in which case the artifact extension is .extA only
 		extension="$(grep -E -o '(\.[a-z][a-zA-Z0-9\-_~]*)*$' <<< "$i")"
 		artifacts+=(".build/$cname-$COMMIT${extension%~*}")
 	done