Documented ARGS_ handling in args().

2 files changed, 18 insertions, 3 deletions

diff --git a/libmdoc.h b/libmdoc.h
index 22233a76..b9668ee1 100644
--- a/libmdoc.h
+++ b/libmdoc.h
@@ -172,9 +172,9 @@ int		  mdoc_args(struct mdoc *, int,
 			int *, char *, int, char **);
 int		  mdoc_zargs(struct mdoc *, int, 
 			int *, char *, int, char **);
-#define	ARGS_DELIM	(1 << 1)
-#define	ARGS_TABSEP	(1 << 2)
-#define	ARGS_NOWARN	(1 << 3)
+#define	ARGS_DELIM	(1 << 1)	/* See args(). */
+#define	ARGS_TABSEP	(1 << 2)	/* See args(). */
+#define	ARGS_NOWARN	(1 << 3)	/* See args(). */
 #define	ARGS_ERROR	(-1)
 #define	ARGS_EOLN	(0)
 #define	ARGS_WORD	(1)
diff --git a/mdoc_argv.c b/mdoc_argv.c
index adafc7b1..447126ef 100644
--- a/mdoc_argv.c
+++ b/mdoc_argv.c
@@ -375,6 +375,21 @@ args(struct mdoc *m, int line, int *pos,
 	int		  i;
 	char		 *p, *pp;
 
+	/*
+	 * Parse out the terms (like `val' in `.Xx -arg val' or simply
+	 * `.Xx val'), which can have all sorts of properties:
+	 *
+	 *   ARGS_DELIM: use special handling if encountering trailing
+	 *   delimiters in the form of [[::delim::][ ]+]+.
+	 *
+	 *   ARGS_NOWARN: don't post warnings.  This is only used when
+	 *   re-parsing delimiters, as the warnings have already been
+	 *   posted.
+	 *
+	 *   ARGS_TABSEP: use special handling for tab/`Ta' separated
+	 *   phrases like in `Bl -column'.
+	 */
+
 	assert(*pos);
 	assert(' ' != buf[*pos]);