Change comment style to use @foo rather than FOO

... when referring to a function's parameter or a struct/union's
member.

The idea of using FOO comes from the GNU coding standards:

    The comment on a function is much clearer if you use the argument
    names to speak about the argument values.  The variable name
    itself should be lower case, but write it in upper case when you
    are speaking about the value rather than the variable itself.
    Thus, "the inode number NODE_NUM" rather than "an inode".

Upcasing names is problematic for a case-sensitive language like C,
because it can create ambiguity.  Moreover, it's too much shouting for
my taste.

GTK-Doc's convention to prefix the identifier with @ makes references
to variables stand out nicely.  The rest of the GTK-Doc conventions
make no sense for us, however.

Signed-off-by: Markus Armbruster <armbru@pond.sub.org>

src/lib/gen/chance.c

@@ -50,7 +50,7 @@ chance(double d)
 }
 
 /*
- * Return non-zero with probability PCT%.
+ * Return non-zero with probability @pct%.
  */
 int
 pct_chance(int pct)
@@ -98,8 +98,8 @@ roll(int n)
 }
 
 /*
- * Round VAL to nearest integer (on the average).
- * VAL's fractional part is chance to round up.
+ * Round @val to nearest integer (on the average).
+ * @val's fractional part is chance to round up.
  */
 int
 roundavg(double val)
@@ -109,7 +109,7 @@ roundavg(double val)
 }
 
 /*
- * Seed the pseudo-random number generator with SEED.
+ * Seed the pseudo-random number generator with @seed.
  * The sequence of pseudo-random numbers is repeatable by seeding it
  * with the same value.
  */

src/lib/gen/fnameat.c

@@ -38,9 +38,9 @@
 static int fname_is_abs(const char *);
 
 /*
- * Interpret FNAME relative to directory DIR.
- * Return FNAME if it is absolute, or DIR is null or empty.
- * Else return a malloc'ed string containing DIR/FNAME, or null
+ * Interpret @fname relative to directory @dir.
+ * Return @fname if it is absolute, or @dir is null or empty.
+ * Else return a malloc'ed string containing @dir/@fname, or null
  * pointer when that fails.
  */
 char *
@@ -73,8 +73,8 @@ fname_is_abs(const char *fname)
 
 /*
  * Open a stream like fopen(), optionally relative to a directory.
- * This is exactly like fopen(), except FNAME is interpreted relative
- * to DIR if that is neither null nor empty.
+ * This is exactly like fopen(), except @fname is interpreted relative
+ * to @dir if that is neither null nor empty.
  */
 FILE *
 fopenat(const char *fname, const char *mode, const char *dir)

src/lib/gen/fsize.c

@@ -52,7 +52,7 @@ fsize(int fd)
 }
 
 /*
- * Return the preferred block size for I/O on FD.
+ * Return the preferred block size for I/O on @fd.
  */
 int
 blksize(int fd)

src/lib/gen/log.c

@@ -51,7 +51,7 @@ static int logfd = -1;
 static int logopen(void);
 
 /*
- * Points log file at PROGRAM.log
+ * Points log file at @program.log
  */
 int
 loginit(char *program)
@@ -123,7 +123,7 @@ logerror(char *format, ...)
 }
 
 /*
- * Log internal error MSG occured in FILE:LINE, call oops handler.
+ * Log internal error @msg occured in @file:@line, call oops handler.
  */
 void
 oops(char *msg, char *file, int line)

src/lib/gen/parse.c

@@ -36,19 +36,19 @@
 #include "prototypes.h"
 
 /*
- * Parse user command in BUF.
- * BUF is UTF-8.
- * Command name and arguments are copied into SPACE[], whose size must
- * be at least strlen(BUF) + 1.
- * Set ARG[0] to the zero-terminated command name.
- * Set ARG[1..N] to the zero-terminated arguments, where N is the
- * number of arguments.  Set ARG[N+1..127] to NULL.
- * Set TAIL[0..N] to beginning of ARG[0] in BUF[].
- * If CONDP is not null, recognize conditional argument syntax, and
- * set *CONDP to the conditional argument if present, else NULL.
- * If REDIR is not null, recognize redirection syntax, and set *REDIR
+ * Parse user command in @buf.
+ * @buf is UTF-8.
+ * Command name and arguments are copied into @space[], whose size must
+ * be at least strlen(@buf) + 1.
+ * Set @arg[0] to the zero-terminated command name.
+ * Set @arg[1..N] to the zero-terminated arguments, where N is the
+ * number of arguments.  Set @arg[N+1..127] to NULL.
+ * Set @tail[0..N] to beginning of @arg[0] in @buf[].
+ * If @condp is not null, recognize conditional argument syntax, and
+ * set *@condp to the conditional argument if present, else NULL.
+ * If @redir is not null, recognize redirection syntax, and set *@redir
  * to UTF-8 redirection string if present, else NULL.
- * Return number of slots used in ARG[], or -1 on error.
+ * Return number of slots used in @arg[], or -1 on error.
  */
 int
 parse(char *buf, char *space, char **arg,