Document arguments in 'contrib/utilities/indent'.

diff --git a/contrib/utilities/indent b/contrib/utilities/indent
index 20dcab3cb9ec7ceba1ef433c698e22a216202992..ab8b209058d215dbacab9414e6758e8d1536d430 100755 (executable)
--- a/contrib/utilities/indent
+++ b/contrib/utilities/indent
@@ -64,6 +64,17 @@ fi
 # Collect all header and source files and process them in batches of 50
 # files with up to 10 in parallel
 #
+# The command line is a bit complicated, so let's discuss the more
+# complicated arguments:
+# - For 'find', -print0 makes sure that file names are separated by \0
+#   characters, as opposed to the default \n. That's because, surprisingly,
+#   \n is a valid character in a file name, whereas \0 is not -- so it
+#   serves as a good candidate to separate individual file names.
+# - For 'xargs', -0 does the opposite: it separates filenames that are
+#   delimited by \0
+# - -n 50 calls the following script with up to 50 file names at a time
+# - -P 10 calls the following script up to 10 times in parallel
+#
 find tests include source examples \
   \( -name '*.cc' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) -print0 |
   xargs -0 -n 50 -P 10 clang-format -i
@@ -119,5 +130,22 @@ format_inst()
 }
 export -f format_inst
 
+#
+# Now do the formatting. The arguments are as discussed above, plus the
+# following:
+# - '-n 1' implies that the following script is called for each file
+#  individually
+# - '-I {}' tells 'xargs' to substitute '{}' in the following by the
+#   one file name we process at a time
+# - 'bash -c' executes the command that follows. Here, this is
+#   'format_inst "$@"' where 'format_inst' is the macro exported
+#   above, and '$@' expands to the list of arguments passed on the
+#   command line, starting at $1. Because we execute a command with
+#   -c, there is no $0 for this bash invokation, and if we just had
+#   {} following the argument of -c, then the first element of that
+#   list would be ignored. To avoid this, we need a dummy argument
+#   to take the role of $0 so that {} can be expanded into $1. We
+#   simply use '_' here, but any other string would do fine as well.
+#
 find source -name '*.inst.in' -print0 |
   xargs -0 -n 1 -P 10 -I {} bash -c 'format_inst "$@"' _ {}