ob_parse_control(): Document

1 files changed, 23 insertions, 0 deletions

diff --git a/lib/control.sh b/lib/control.sh
index fd07bed..fcb649f 100644
--- a/lib/control.sh
+++ b/lib/control.sh
@@ -51,6 +51,29 @@ _ob_parse_control_error()
 	return 0
 }
 
+## @brief Parse a control file
+## @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 after
+##          setting \fIOB_CONTROL_NAME\fP to the field name and
+##          \fIOB_CONTROL_VALUE\fP to the field value.  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 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.
+## @return Returns 0 after parsing, or 125 if called with an incorrect number of
+##         arguments.
+## @stderr Prints error messages on parse errors.
+## @pure maybe This function sets global variables, but they're only intended
+##             for use by \fIfield_cb\fP, which is called during the lifetime of
+##             this function.  Whether this function is subshell-safe in
+##             practice depends on whether \fIfield_cb\fP is subshell-safe.
 ob_parse_control()
 {
 	local file=