X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/4f634d205ba36abb1a9b0a0d81a2912f1b3ff96a..e895be217c3be6769708da17c9ae87cb22db040e:/lib/keyword.3

diff --git a/lib/keyword.3 b/lib/keyword.3
index db5b86d..7847733 100644
--- a/lib/keyword.3
+++ b/lib/keyword.3
@@ -402,15 +402,41 @@ argument consists of a sequence of calls to
 the keyword-argument macros described below,
 one after another without any separation.
 .PP
-In C89, macro actual arguments are not permitted to be empty;
-if there are no keyword arguments to provide,
-then the argument-less macro
+If there are no keyword arguments,
+use the argument-less macro
 .B NO_KWARGS
-should be used instead.
-If you're using C99 or later,
-it's fine to just write
-.B KWARGS()
 instead.
+There are two reasons for this.
+.hP \*o
+C89 doesn't permit empty macro arguments for some reason,
+so
+.B NO_KWARGS
+is necessary when using a C89 compiler.
+.hP \*o
+Omitting the null terminator is a common mistake,
+so
+.B <keyword.h>
+tries to get the compiler to warn if you miss it.
+However, the
+.B KWTAIL
+macro introduces an extra real argument
+.BR kwfirst_ ,
+because it's not possible to scan a variable-length argument tail
+if there are no mandatory arguments.
+If you use
+.BR KWARGS() ,
+with an empty argument list,
+then the null terminator is passed as
+.B kwfirst_
+and the variable-length tail ends up empty,
+which might trigger a compiler warning
+about the missing terminator.
+.B NO_KWARGS
+passes
+.I two
+null terminators:
+a real one to indicate that there are no keyword arguments,
+and a dummy one to placate the compiler.
 .PP
 The following keyword-argument macros can be used
 within