From 253328e2651384dbdfaa06dc153268bc17ad840b Mon Sep 17 00:00:00 2001
From: Patrick McDermott <patrick.mcdermott@libiquity.com>
Date: Sat, 05 Jan 2019 11:05:51 -0500
Subject: ob_parse_control(): Update/improve field_cb documentation

---
(limited to 'lib/control.sh')

diff --git a/lib/control.sh b/lib/control.sh
index 0bdf77c..234a375 100644
--- a/lib/control.sh
+++ b/lib/control.sh
@@ -52,15 +52,18 @@ _ob_parse_control_error()
 ## @details \fBob_parse_control\fP parses a control file of field names and
 ##          values formatted like RFC 822 (or RFC 2822 or RFC 5322) headers. 
 ##          For each field, \fBob_parse_control\fP calls \fIfield_cb\fP with the
-##          field name and value as arguments.  If \fIreq_fields\fP and
-##          \fIopt_fields\fP are given, \fBob_parse_control\fP verifies that the
-##          input control file contains all fields listed in \fIreq_fields\fP
-##          and no fields that are listed in neither \fIreq_fields\fP nor
-##          \fIopt_fields\fP.  If \fIfield_cb\fP returns non-zero,
-##          \fBob_parse_control\fP stops parsing and immediately returns,
-##          without verifying that all required fields were found.
+##          field name, the field value, and \fIuser_data\fP as arguments.  If
+##          \fIreq_fields\fP and \fIopt_fields\fP are given,
+##          \fBob_parse_control\fP verifies that the input control file contains
+##          all fields listed in \fIreq_fields\fP and no fields that are listed
+##          in neither \fIreq_fields\fP nor \fIopt_fields\fP.  If \fIfield_cb\fP
+##          returns non-zero, \fBob_parse_control\fP stops parsing and
+##          immediately returns, without verifying that all required fields were
+##          found.
 ## @operand file       req The control file to parse, or "-" for standard input.
-## @operand field_cb   req Callback to run for each field.
+## @operand field_cb   req Callback to run for each field.  Must accept three
+##                     arguments: the field name, the field value, and
+##                     \fIuser_data\fP.
 ## @operand user_data  req Data to pass to \fIfield_cb\fP.
 ## @operand req_fields opt Required fields that must appear in the control file.
 ## @operand opt_fields opt Optional fields that may appear in the control file.
--
cgit v0.9.1