From 140c572128a09324f6f907ca8b3583c5f422e210 Mon Sep 17 00:00:00 2001
From: Ben Hutchings <benh@debian.org>
Date: Thu, 26 Sep 2024 18:01:04 +0200
Subject: [PATCH] hook-functions: Expand documentation of copy_exec and
 copy_file

The documentation is currently a bit vague and doesn't mention
creation of directories or symlinks at all.  Expand it to describe the
current behaviour.

Signed-off-by: Ben Hutchings <benh@debian.org>
---
 hook-functions | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

diff --git a/hook-functions b/hook-functions
index d3f7a32..f673292 100644
--- a/hook-functions
+++ b/hook-functions
@@ -150,12 +150,27 @@ add_builtin_firmware()
 	done
 }
 
-# $1 = file type (for logging)
-# $2 = file to copy to initramfs
-# $3 (optional) Name for the file on the initramfs
-# Location of the image dir is assumed to be $DESTDIR
-# If the target exists, we leave it and return 1.
-# On any other error, we return >1.
+# Copy a file to the initramfs:
+# $1 = file type, for debug logging
+# $2 = source file name
+# $3 (optional) = target file or directory name in the initramfs
+#
+# * If the target is not specified, it defaults to the source file
+#   name.
+# * If the target is specified and exists as a directory under
+#   $DESTDIR, the basename of the source is appended to it.
+#
+# The target file's containing directories are created if necessary.
+#
+# If the source file name includes a symlink, and the canonical name
+# of the source is not the same as the target, the source file is
+# copied to its canonical name in the initramfs and the target is
+# created as a symlink.
+#
+# Returns:
+# * If the file was copied successfully, 0
+# * If the target file already existed, 1
+# * On error, >1
 copy_file() {
 	local type src target link_target
 
@@ -216,10 +231,16 @@ copy_file() {
 	cp -pP "${src}" "${DESTDIR}/${target}" || return $(($? + 1))
 }
 
-# $1 = executable/shared library to copy to initramfs, with dependencies
-# $2 (optional) Name for the file on the initramfs
-# Location of the image dir is assumed to be $DESTDIR
-# We never overwrite the target if it exists.
+# Copy an executable or shared library to the initramfs:
+# $1 = source file name
+# $2 (optional) = target file or directory name in the initramfs
+#
+# The source and all its shared library dependencies are copied
+# using copy_file.
+#
+# Returns:
+# * If the files were copied successfully or already exited, 0
+# * On error, >0
 copy_exec() {
 	local src target x nonoptlib ret