[ng] cosmetics: add comments about few internal variables

* lib/am/header-vars.mk (am.hack.rm-f, am.hack.rm-rf,am.clean-cmd.f,
am.clean-cmd.d): These.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

diff --git a/lib/am/header-vars.mk b/lib/am/header-vars.mk
index 24cec94ab6820d992707631e96af987f3a6daaa5..1cfed959d0cf9ceba5e98c9cb18f4c7cb8ab6842 100644 (file)
--- a/lib/am/header-vars.mk
+++ b/lib/am/header-vars.mk
@@ -309,9 +309,26 @@ $(if $2,$(strip \
   )$(if $($0.counter),$(call $1,$(strip $($0.partial-args)))))
 endef
 
+# Used only by the 'am.clean-cmd.*' functions below.  Do not use in
+# other places.
 am.hack.rm-f = $(if $(strip $1),rm -f $(strip $1)$(am.chars.newline))
 am.hack.rm-rf = $(if $(strip $1),rm -rf $(strip $1)$(am.chars.newline))
 
+# Needed to ensure the invocations of "rm -f" and "rm -rf" in our cleaning
+# rules are not given too many arguments, which might cause command line
+# length limits to be exceeded.  These are only meant to be used in a
+# "sub-recipe" by their own; e.g.,
+#
+#    # This is ok.
+#    clean-x:
+#        @echo "Cleaning X Files"
+#        @$(call am.clean-cmd.f,$(X_FILES))
+#
+#    # This is *wrong*.
+#    clean-x:
+#        @echo "Cleaning X Files" \
+#          && $(call am.clean-cmd.f,$(X_FILES))
+#
 am.clean-cmd.f = $(call am.xargs-map,am.hack.rm-f,$1)
 am.clean-cmd.d = $(call am.xargs-map,am.hack.rm-rf,$1)