#96: documenting variable utils

mk/util/var.mk

@@ -1,10 +1,26 @@
 #
 # Variable assignment utils.
 #
+# Note: The most functions here are highly optimized using inlining, make
+# version-specific features, and so on.
+# This is achieved at the expense of the code readability and simplicity,
+# so it is assumed that the reader will not dig into the internals of how does
+# it work. You've been warned.
+# If you anyway want to understand how it works, there are some cheats at the
+# bottom of this file. ;-)
+#
 # Author: Eldar Abusalimov
 #
 
-
+#
+# Expands to the variable information string.
+# Information includes flavor, origin and value of the specified variable.
+#
+# Params:
+#  1. The target variable name
+#
+# Returns: Human-readable multiline string containing variable information.
+#
 define var_dump
 $(call assert_called,var_dump,$0) \
   $(call assert,$1,Variable name is empty) Variable [$1] info:
@@ -14,8 +30,97 @@ $(call assert_called,var_dump,$0) \
 
 endef
 
+#
+# Prints the information about the specified variable using $(info) function.
+#
+# Params:
+#  1. The target variable name
+#
+# Returns: nothing
+#
+# See also: var_dump
+#
 var_info = $(call assert_called,var_info,$0)$(info $(call var_dump,$1))
 
+#
+# Function: var_assign_recursive, =
+#
+# Assigns value to the specified variable, the variable becomes recursively
+# expanded.
+# This function is backed either by var_assign_singleline_recursive or by
+# var_assign_multiline_recursive, the proper choice is made by checking for
+# newline character $(\n) in the value being assigned.
+#
+# Params:
+#  1. The target variable name
+#  2. The value to assign
+#
+# Returns: nothing
+#
+# Note: the underlying implementation uses $(eval) function for the assignment,
+#       and all notes about its arguments are applied for this case too
+#       (see GNU Make manual).
+#
+# See also: var_assign_singleline_recursive var_assign_multiline_recursive
+#
+
+#
+# Function: var_assign_singleline_recursive
+#
+# Assigns value to the specified variable, the variable becomes recursively
+# expanded. The value must not contain any newline characters.
+#
+# Params:
+#  1. The target variable name
+#  2. The value to assign
+#
+# Returns: nothing
+#
+# Note: the underlying implementation uses $(eval) function for the assignment,
+#       and all notes about its arguments are applied for this case too
+#       (see GNU Make manual).
+#
+# Note: all that this function does is just evaluates something like:
+#       $1 = $2
+#
+
+#
+# Function: var_assign_simple, =:
+#
+# Assigns value to the specified variable using immediate expansion (variable
+# flavor becomes simple).
+#
+# Params:
+#  1. The target variable name
+#  2. The value to assign
+#
+# Returns: nothing
+#
+# Note: the underlying implementation uses $(eval) function for the assignment,
+#       and all notes about its arguments are applied for this case too
+#       (see GNU Make manual).
+#
+
+var_assign_undefined
+var_assign_recursive
+var_assign_simple
+var_assign_append
+var_assign_cond
+=
+=:
+=+
+=?
+var_assign_singleline_recursive
+var_assign_singleline_simple
+var_assign_singleline_append
+var_assign_singleline_cond
+var_assign_multiline_recursive
+var_assign_multiline_simple
+var_assign_multiline_append
+var_assign_multiline_cond
+
+# Here goes the implementation.
+
 # Include version-specific file.
 #
 # It have to define __var_assign_<line>_<op>_mk variables (8 ones total),
@@ -100,27 +205,28 @@ __var_assign_autoline_def = ${eval $ \
   )}$ \
 }
 
+__var_assign_op_escaped_name = =$(subst =,,$(__var_assign_op_$2))
 $(foreach op,$(__var_assign_ops), \
-  $(foreach def,var_assign_$(op) $$(__var_assign_op_$(op)), \
+  $(foreach def,var_assign_$(op) $$(__var_assign_op_escaped_name), \
     $(call __var_assign_autoline_def,$(def),$(op)) \
   ) \
 )
 
 # Yes, everything above may look horrible, but it is only at first sight.
-# If you are trying to understand how does it work,
-# just enable the following block.
-# -- Eldar
+# Enabling the following block may help you to understand what is happening
+# when one or another function is being expanded.
+#  -- Eldar
 ifeq (1,0)
 __var_info_simplified = $(info $1 = $(value $(strip $1))$(\n))
 $(call __var_info_simplified,var_assign_undefined)
 $(call __var_info_simplified,var_assign_recursive)
 $(call __var_info_simplified,var_assign_simple   )
 $(call __var_info_simplified,var_assign_append   )
 $(call __var_info_simplified,var_assign_cond     )
-$(call __var_info_simplified, =)
-$(call __var_info_simplified,:=)
-$(call __var_info_simplified,+=)
-$(call __var_info_simplified,?=)
+$(call __var_info_simplified,= )
+$(call __var_info_simplified,=:)
+$(call __var_info_simplified,=+)
+$(call __var_info_simplified,=?)
 $(call __var_info_simplified,var_assign_singleline_recursive)
 $(call __var_info_simplified,var_assign_singleline_simple   )
 $(call __var_info_simplified,var_assign_singleline_append   )