From 8239310ded50306bf3e250716c22753d41f08a96 Mon Sep 17 00:00:00 2001
From: Anthony Ramine <n.oxyde@gmail.com>
Date: Tue, 22 Jan 2013 21:19:10 +0100
Subject: Document output.mk.in

Conflicts:

	make/output.mk.in
---
 make/output.mk.in | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/make/output.mk.in b/make/output.mk.in
index 2f1a1d3a79..de60d03b91 100644
--- a/make/output.mk.in
+++ b/make/output.mk.in
@@ -22,19 +22,35 @@
 # Author: Anthony Ramine
 # ----------------------------------------------------
 
+# These variables are used to produce less output when running make with V=0 or
+# with the --enable-silent-rules flag.
+#
+# For each compiler kind of file generated by a command during the building of
+# Erlang/OTP, a variable named <command>_verbose should be defined and used as
+# a command prefix. The generic gen_verbose variable is offered for
+# miscellaneous operations like sed, cp or magical Perl incantations.
+#
+# A second variable V_<COMMAND> is also provided for major compilation tools
+# like CC, ERLC or JAVAC.
+
+# DEFAULT_VERBOSITY is set by the --enable-silent-rules configure flag.
 ifeq ($(V),)
 V = @DEFAULT_VERBOSITY@
 endif
 
+# v_p should be used with `test` to dynamically print things.
 ifeq ($(V),0)
 v_p = 0
 else
 v_p = 1
 endif
 
+# V_at is the @ prefix when silent rules are enabled.
 V_at_0 = @
 V_at = $(V_at_$(V))
 
+# V_colon makes the prefixed command into a no-op if silent rules are enabled,
+# useful to annihilate an `echo` command.
 V_colon_0 = @: ""
 V_colon = $(V_colon_$(V))
 
@@ -49,6 +65,10 @@ cc_verbose_0 = @echo " CC	"$@;
 cc_verbose = $(cc_verbose_$(V))
 V_CC = $(cc_verbose)$(CC)
 
+cpp_verbose_0 = @echo " CPP	"$@;
+cpp_verbose = $(cpp_verbose_$(V))
+
+# For the diameter compiler.
 dia_verbose_0 = @echo " DIA	"$@;
 dia_verbose = $(dia_verbose_$(V))
 
@@ -87,6 +107,11 @@ V_LEX = $(lex_verbose)$(LEX)
 m4_verbose_0 = @echo " M4	"$@;
 m4_verbose = $(m4_verbose_$(V))
 
+# V_MAKE isn't defined and shouldn't be to avoid breaking parallel building and
+# the following warning:
+#
+#     warning: jobserver unavailable: using -j1. Add `+' to parent make rule.
+#
 make_verbose_0 = @echo " MAKE	"$@;
 make_verbose = $(make_verbose_$(V))
 
@@ -105,6 +130,8 @@ V_RC = $(rc_verbose)$(RC)
 snmp_verbose_0 = @echo " SNMP	"$@;
 snmp_verbose = $(snmp_verbose_$(V))
 
+# vsn_verbose should be used instead of gen_verbose when sed or another tool
+# is used to insert a version number into a file.
 vsn_verbose_0 = @echo " VSN	"$@;
 vsn_verbose = $(vsn_verbose_$(V))
 
-- 
cgit v1.2.3