>From 974d478d5f1f64235d67160b0419cb93ae1a7f6c Mon Sep 17 00:00:00 2001
Message-Id: <address@hidden>
From: Stefano Lattarini <address@hidden>
Date: Wed, 1 Aug 2012 10:00:47 +0200
Subject: [PATCH] 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 <address@hidden>
---
 lib/am/header-vars.mk | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/lib/am/header-vars.mk b/lib/am/header-vars.mk
index 24cec94..1cfed95 100644
--- 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)
 
-- 
1.7.12.rc0