From 28cfda76882f2c67fbda20831352cc7f65e64ad2 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Mon, 4 May 2015 11:00:12 +0100
Subject: [PATCH] defs.m4: Fix commentary, and add missing descriptions.

---
 defs.m4 | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/defs.m4 b/defs.m4
index f9b3333..c289385 100644
--- a/defs.m4
+++ b/defs.m4
@@ -45,7 +45,7 @@ m4_divert(-1)
 m4_define(<:ONEOF:>, <:m4_ifelse(<:$#:>, <:1:>, <:$1:>,
 	<:$1:>, <::>, <:ONEOF(m4_shift($@)):>, <:$1:>):>)
 
-## DEFCONF(CONF, DEFAULT)
+## DEFCONF(conf, default)
 ##
 ## Define config variable CONF, assigning it the DEFAULT value if not
 ## overridden by `SETCONF'.
@@ -53,7 +53,7 @@ m4_define(<:DEFCONF:>,
 <:m4_ifdef(<:CONF_$1:>, <::>,
 <:m4_define(<:CONF_$1:>, <:$2:>):>):>)
 
-## SETCONF(CONF, VALUE)
+## SETCONF(conf, value)
 ##
 ## Set config variable VALUE.
 m4_define(<:SETCONF:>, <:m4_define(<:CONF_$1:>, <:$2:>):>)
@@ -73,10 +73,19 @@ m4_pushdef(<:_foreach_func:>, <:$1:>)m4_dnl
 _FOREACH($2)<::>m4_dnl
 m4_popdef(<:_foreach_func:>):>)
 
+## DIVERT(name)
+##
+## Make _div:NAME be the current diversion.
 m4_define(<:DIVERT:>, <:m4_dnl
 m4_divert(m4_indir(<:_div:$1:>))m4_dnl
 :>)
 
+## SECTION(name, [sub])
+##
+## Contribute the following text to section NAME, inserting appropriate
+## header text to the top of the section if necessary.  If a SUB-section name
+## is given, then the contribution is made to the subsection, and the
+## subsection's header (if any) is also inserted.
 m4_define(<:SECTION:>, <:m4_dnl
 DIVERT(<:$1:>)m4_dnl
 m4_ifdef(<:_done:$1:>, <::>, <:m4_dnl
@@ -90,6 +99,13 @@ m4_ifdef(<:_done:$1/$2:>, <::>, <:m4_dnl
 m4_ifdef(<:_head:$1/$2:>, <:<:##:> m4_indir(<:_head:$1/$2:>)
 :>)m4_define(<:_done:$1/$2:>):>):>):>)
 
+## LOOKUP_DOMAIN(dom, [if-found], [if-not-found])
+##
+## Look up DOM in the master domains file.  If it's found, put the
+## information found in `$value' and expand to IF-FOUND, which may use `KV'
+## to extract keyword values, and defaults to `$value'; otherwise, obey
+## IF-NOT-FOUND, which may be the token `fail', or replacement text in
+## braces.
 m4_define(<:LOOKUP_DOMAIN:>,
 	<:if exists{CONF_sysconf_dir/domains.conf} \
 	     {${lookup {$1}partial0-lsearch{CONF_sysconf_dir/domains.conf} \
@@ -98,7 +114,19 @@ m4_define(<:LOOKUP_DOMAIN:>,
 				 <:$2$3:>)}} \
 	     $3:>)
 
+## KV(key, result)
+##
+## Extract the value of the named KEY in the ${extract ...}-style string in
+## the current $value (where it may have been left by `LOOKUP-DOMAIN').  The
+## RESULT is a pair {IF-FOUND}{IF-NOT-FOUND}; the former may use $value to
+## refer to the value; the latter may be `fail' (not in braces) to force
+## expansion failure.
 m4_define(<:KV:>, <:${extract {$1}{$value}$2}:>)
+
+## DOMKV(key, result)
+##
+## Extract the value of the named KEY in the ${extract ...}-style string in
+## $domain_data; see `KV'.
 m4_define(<:DOMKV:>, <:${extract {$1}{$domain_data}$2}:>)
 
 m4_divert(999)m4_dnl
-- 
2.11.0