X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/3a774b55edfea441c1715994924c2999e9202143..c6b4ed992d81518f240509e6ab212d8fe705485a:/lib/keyword.3

diff --git a/lib/keyword.3 b/lib/keyword.3
index a0c6173..7847733 100644
--- a/lib/keyword.3
+++ b/lib/keyword.3
@@ -212,6 +212,17 @@ Argument vectors are rather inconvenient to use,
 but are the only practical way in which a caller can decide at runtime
 which arguments to include in a call,
 which is useful when writing wrapper functions.
+.PP
+Perhaps surprisingly,
+keyword arguments have a relatively small performance impact.
+On the author's aging laptop,
+a call to a simple function,
+passing two out of three keyword arguments,
+takes about 30 cycles longer than
+calling a standard function which just takes integer arguments.
+On the other hand,
+quite a lot of code is involved in decoding keyword arguments,
+so code size will naturally suffer.
 .
 .SS Type definitions
 The header file defines two simple structure types.
@@ -391,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
@@ -817,7 +854,7 @@ storing the results in
 It assumes that the first keyword name
 is in an argument named
 .BR kwfirst_ ,
-as set up by
+as set up by the
 .B KWTAIL
 marker described above.
 .PP