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>

include/empthread.h

@@ -101,8 +101,8 @@ void empth_request_shutdown(void);
 
 /*
  * Initialize thread package.
- * CTX points to a thread context variable; see empth_create().
+ * @ctx points to a thread context variable; see empth_create().
- * FLAGS request optional features.
+ * @flags request optional features.
  * Should return 0 on success, -1 on error, but currently always
  * returns 0.
  */
@@ -110,12 +110,12 @@ int empth_init(void **ctx, int flags);
 
 /*
  * Create a new thread.
- * ENTRY is the entry point.  It will be called with argument UD.
+ * @entry is the entry point.  It will be called with argument @ud.
  * If it returns, the thread terminates as if it called empth_exit().
- * Thread stack is at least SIZE bytes.
+ * Thread stack is at least @size bytes.
- * FLAGS should be the same as were passed to empth_init(), or zero.
+ * @flags should be the same as were passed to empth_init(), or zero.
- * NAME is the thread's name, it is used for logging and debugging.
+ * @name is the thread's name, it is used for logging and debugging.
- * UD is the value to pass to ENTRY.  It is also assigned to the
+ * @ud is the value to pass to @entry.  It is also assigned to the
  * context variable defined with empth_init() whenever the thread gets
  * scheduled.
  * Yield the processor.
@@ -131,12 +131,12 @@ empth_t *empth_create(void (*entry)(void *),
 empth_t *empth_self(void);
 
 /*
- * Return THREAD's name.
+ * Return @thread's name.
  */
 char *empth_name(empth_t *thread);
 
 /*
- * Set THREAD's name to NAME.
+ * Set @thread's name to @name.
  */
 void empth_set_name(empth_t *thread, char *name);
 
@@ -155,27 +155,27 @@ void empth_exit(void);
 void empth_yield(void);
 
 /*
- * Put current thread to sleep until file descriptor FD is ready for I/O.
+ * Put current thread to sleep until file descriptor @fd is ready for I/O.
- * If FLAGS & EMPTH_FD_READ, wake up if FD is ready for input.
+ * If @flags & EMPTH_FD_READ, wake up if @fd is ready for input.
- * If FLAGS & EMPTH_FD_WRITE, wake up if FD is ready for output.
+ * If @flags & EMPTH_FD_WRITE, wake up if @fd is ready for output.
  * At most one thread may sleep on the same file descriptor.
- * TIMEOUT, if non-null, limits the sleep time.
+ * @timeout, if non-null, limits the sleep time.
- * Return one when the FD is ready, zero on timeout or early wakeup by
+ * Return one when the @fd is ready, zero on timeout or early wakeup by
  * empth_wakeup(), -1 on error with errno set.
- * Note: Currently, Empire sleeps only on network I/O, i.e. FD is a
+ * Note: Currently, Empire sleeps only on network I/O, i.e. @fd is a
  * socket.  Implementations should not rely on that.
  */
 int empth_select(int fd, int flags, struct timeval *timeout);
 
 /*
- * Awaken THREAD if it is sleeping in empth_select() or empth_sleep().
+ * Awaken @thread if it is sleeping in empth_select() or empth_sleep().
  * This does not awaken threads sleeping in other functions.
  * Does not yield the processor.
  */
 void empth_wakeup(empth_t *thread);
 
 /*
- * Put current thread to sleep until the time is UNTIL.
+ * Put current thread to sleep until the time is @until.
  * Return 0 if it slept until that time.
  * Return -1 if woken up early, by empth_wakeup().
  */
@@ -189,18 +189,18 @@ int empth_wait_for_signal(void);
 
 /*
  * Create a read-write lock.
- * NAME is its name, it is used for debugging.
+ * @name is its name, it is used for debugging.
  * Return the read-write lock, or NULL on error.
  */
 empth_rwlock_t *empth_rwlock_create(char *name);
 
 /*
- * Destroy RWLOCK.
+ * Destroy @rwlock.
  */
 void empth_rwlock_destroy(empth_rwlock_t *rwlock);
 
 /*
- * Lock RWLOCK for writing.
+ * Lock @rwlock for writing.
  * A read-write lock can be locked for writing only when it is
  * unlocked.  If this is not the case, put the current thread to sleep
  * until it is.
@@ -208,7 +208,7 @@ void empth_rwlock_destroy(empth_rwlock_t *rwlock);
 void empth_rwlock_wrlock(empth_rwlock_t *rwlock);
 
 /*
- * Lock RWLOCK for reading.
+ * Lock @rwlock for reading.
  * A read-write lock can be locked for reading only when it is not
  * locked for writing, and no other thread is attempting to lock it
  * for writing.  If this is not the case, put the current thread to
@@ -217,8 +217,8 @@ void empth_rwlock_wrlock(empth_rwlock_t *rwlock);
 void empth_rwlock_rdlock(empth_rwlock_t *rwlock);
 
 /*
- * Unlock read-write lock RWLOCK.
+ * Unlock read-write lock @rwlock.
- * The current thread must hold RWLOCK.
+ * The current thread must hold @rwlock.
  * Wake up threads that can now lock it.
  */
 void empth_rwlock_unlock(empth_rwlock_t *rwlock);

include/map.h

@@ -36,15 +36,15 @@
 #include "types.h"
 
 /*
- * Width of the body of a map using PERSEC characters per sector.
+ * Width of the body of a map using @persec characters per sector.
  *
  * One row shows WORLD_X/2 sectors, separated by one space.  Requires
- * WORLD_X/2 * (PERSEC+1) - 1 characters.
+ * WORLD_X/2 * (@persec+1) - 1 characters.
  *
  * Every other row is indented so that the center of the first sector
  * is aligned with the space separating the first two sectors in the
- * adjacent rows.  For odd PERSEC, that's (PERSEC+1)/2 additional
+ * adjacent rows.  For odd @persec, that's (@persec+1)/2 additional
- * characters.  For even PERSEC, it's either PERSEC/2 or PERSEC/2 + 1,
+ * characters.  For even @persec, it's either @persec/2 or @persec/2 + 1,
  * depending on whether we align the character left or right of the
  * center with the space (the map will look rather odd either way).
  *

include/misc.h

@@ -60,8 +60,8 @@
 #define days(x)		(60*60*24*(x))
 
 /*
- * If EXPR is true, an internal error occured.
+ * If @expr is true, an internal error occured.
- * Return EXPR != 0.
+ * Return @expr != 0.
  * Usage: if (CANT_HAPPEN(...)) <recovery code>;
  */
 #define CANT_HAPPEN(expr) ((expr) ? oops(#expr, __FILE__, __LINE__), 1 : 0)

include/nsc.h

@@ -86,10 +86,10 @@ enum nsc_cat {
  * Value, possibly symbolic
  *
  * If type is NSC_NOTYPE, it's an error value.
- * If category is NSC_VAL, the value is in val_as, and the type is a
+ * If category is NSC_VAL, the value is in @val_as, and the type is a
  * promoted type.
  * If category is NSC_OFF, the value is in a context object, and
- * val_as.sym specifies how to get it, as follows.
+ * @val_as.sym specifies how to get it, as follows.
  * If sym.get is null, and type is NSC_STRINGY, the value is a string
  * stored in sym.len characters starting at sym.offs in the context
  * object.  sym.idx must be zero.  Ugly wart: if sym.len is one, the
@@ -180,7 +180,7 @@ struct nstr_item {
 };
 
 /*
- * Symbol binding: associate NAME with VALUE.
+ * Symbol binding: associate @name with @value.
  */
 struct symbol {
     int value;
@@ -200,16 +200,16 @@ enum {
  * Selector descriptor
  *
  * A selector describes an attribute of some context object.
- * A selector with ca_type NSC_NOTYPE is invalid.
+ * A selector with @ca_type NSC_NOTYPE is invalid.
- * If ca_get is null, the selector describes a datum of type ca_type
+ * If @ca_get is null, the selector describes a datum of type @ca_type
- * at offset ca_offs in the context object.
+ * at offset @ca_offs in the context object.
  * A datum of type NSC_STRINGY is a string stored in an array of
- * ca_len characters.  Ugly wart: if ca_len is one, the terminating
+ * @ca_len characters.  Ugly wart: if @ca_len is one, the terminating
  * null character may be omitted.
  * A datum of any other type is either a scalar of that type (if
- * ca_len is zero), or an array of ca_len elements of that type.
+ * @ca_len is zero), or an array of @ca_len elements of that type.
- * If ca_get is not null, the selector is virtual.  Values can be
+ * If @ca_get is not null, the selector is virtual.  Values can be
- * obtained by calling ca_get(VAL, NP, CTXO), where VAL has been
+ * obtained by calling @ca_get(VAL, NP, CTXO), where VAL has been
  * initialized from the selector and an index by nstr_mksymval(),
  * NP points to the country to use for coordinate translation and
  * access control (null for none), and CTXO is the context object.
@@ -224,8 +224,8 @@ enum {
  * elements, indexed by country number, and the context object must be
  * EF_NATION.  Array elements are masked for contact when opt_HIDDEN
  * is on.
- * If ca_table is not EF_BAD, the datum refers to that Empire table;
+ * If @ca_table is not EF_BAD, the datum refers to that Empire table;
- * ca_type must be an integer type.  If flag NSC_BITS is set, the
+ * @ca_type must be an integer type.  If flag NSC_BITS is set, the
  * datum consists of flag bits, and the referred table must be a
  * symbol table defining those bits.
  */

src/client/linebuf.c

@@ -38,7 +38,7 @@
 
 /*
  * Initialize empty line buffer.
- * Not necessary if *LBUF is already zeroed.
+ * Not necessary if *@lbuf is already zeroed.
  */
 void
 lbuf_init(struct lbuf *lbuf)
@@ -57,7 +57,7 @@ lbuf_len(struct lbuf *lbuf)
 }
 
 /*
- * Is LBUF full (i.e. we got the newline)?
+ * Is @lbuf full (i.e. we got the newline)?
  */
 int
 lbuf_full(struct lbuf *lbuf)
@@ -79,9 +79,9 @@ lbuf_line(struct lbuf *lbuf)
 }
 
 /*
- * Append CH to the line buffered in LBUF.
+ * Append @ch to the line buffered in @lbuf.
- * LBUF must not be full.
+ * @lbuf must not be full.
- * If CH is a newline, the buffer is now full.  Return the line
+ * If @ch is a newline, the buffer is now full.  Return the line
  * length, including the newline.
  * Else return 0 if there was space, and -1 if not.
  */

src/client/play.c

@@ -309,7 +309,7 @@ int send_eof;				/* need to send EOF_COOKIE */
 static volatile sig_atomic_t send_intr; /* need to send INTR_COOKIE */
 
 /*
- * Receive and process server output from SOCK.
+ * Receive and process server output from @sock.
  * Return number of characters received on success, -1 on error.
  */
 static int
@@ -398,7 +398,7 @@ recv_output(int sock)
 }
 
 /*
- * Receive command input from FD into INBUF.
+ * Receive command input from @fd into @inbuf.
  * Return 1 on receipt of input, zero on EOF, -1 on error.
  */
 static int
@@ -449,7 +449,7 @@ intr(int sig)
 }
 
 /*
- * Play on SOCK.
+ * Play on @sock.
  * The session must be in the playing phase.
  * Return 0 when the session ended, -1 on error.
  */

src/client/ringbuf.c

@@ -69,9 +69,9 @@ ring_space(struct ring *r)
 
 /*
  * Peek at ring buffer contents.
- * N must be between -RING_SIZE-1 and RING_SIZE.
+ * @n must be between -RING_SIZE-1 and RING_SIZE.
- * If N>=0, peek at the (N+1)-th byte to be gotten.
+ * If @n>=0, peek at the (@n+1)-th byte to be gotten.
- * If N<0, peek at the -N-th byte that has been put in.
+ * If @n<0, peek at the -@n-th byte that has been put in.
  * Return the byte as unsigned char coverted to int, or EOF if there
  * aren't that many bytes in the ring buffer.
  */
@@ -102,8 +102,8 @@ ring_getc(struct ring *r)
 }
 
 /*
- * Attempt to put byte C into the ring buffer.
+ * Attempt to put byte @c into the ring buffer.
- * Return EOF when the buffer is full, else C.
+ * Return EOF when the buffer is full, else @c.
  */
 int
 ring_putc(struct ring *r, unsigned char c)
@@ -114,7 +114,7 @@ ring_putc(struct ring *r, unsigned char c)
 }
 
 /*
- * Attempt to put SZ bytes from BUF into the ring buffer.
+ * Attempt to put @sz bytes from @buf into the ring buffer.
  * Return space left in ring buffer when it fits, else don't change
  * the ring buffer and return how much space is missing times -1.
  */
@@ -168,7 +168,7 @@ ring_search(struct ring *r, char *s)
 }
 
 /*
- * Fill ring buffer from file referred by file descriptor FD.
+ * Fill ring buffer from file referred by file descriptor @fd.
  * If ring buffer is already full, do nothing and return 0.
  * Else attempt to read as many bytes as space permits, with readv(),
  * and return its value.
@@ -206,7 +206,7 @@ ring_from_file(struct ring *r, int fd)
 }
 
 /*
- * Drain ring buffer to file referred by file descriptor FD.
+ * Drain ring buffer to file referred by file descriptor @fd.
  * If ring buffer is already empty, do nothing and return 0.
  * Else attempt to write complete contents with writev(), and return
  * its value.

src/client/secure.c

@@ -41,7 +41,7 @@ static struct ring recent_input;
 static size_t saved_bytes;
 
 /*
- * Remember line of input INP for a while.
+ * Remember line of input @inp for a while.
  * It must end with a newline.
  * Return value is suitable for forget_input(): it makes it forget all
  * input up to and including this line.
@@ -64,9 +64,9 @@ save_input(char *inp)
 }
 
 /*
- * Can you still remember a line of input that ends with TAIL?
+ * Can you still remember a line of input that ends with @tail?
  * It must end with a newline.
- * Return non-zero iff TAIL can be remembered.
+ * Return non-zero iff @tail can be remembered.
  * Passing that value to forget_input() will forget all input up to
  * and including this line.
  */
@@ -88,8 +88,8 @@ seen_input(char *tail)
 }
 
 /*
- * Forget remembered input up to SEEN.
+ * Forget remembered input up to @seen.
- * SEEN should be obtained from save_input() or seen_input().
+ * @seen should be obtained from save_input() or seen_input().
  */
 void
 forget_input(size_t seen)

src/lib/commands/flash.c

@@ -79,9 +79,9 @@ wall(void)
 }
 
 /*
- * Send flash message(s) from US to TO.
+ * Send flash message(s) from @us to @to.
- * Null TO broadcasts to all.
+ * Null @to broadcasts to all.
- * MESSAGE is UTF-8.  If it is null, prompt for messages interactively.
+ * @message is UTF-8.  If it is null, prompt for messages interactively.
  * Return RET_OK.
  */
 static int
@@ -107,11 +107,11 @@ chat(struct natstr *to, char *message)
 }
 
 /*
- * Send flash message MESSAGE from US to TO.
+ * Send flash message @message from @us to @to.
- * MESSAGE is UTF-8.
+ * @message is UTF-8.
- * Null TO broadcasts to all.
+ * Null @to broadcasts to all.
- * A header identifying US is prepended to the message.  It is more
+ * A header identifying @us is prepended to the message.  It is more
- * verbose if VERBOSE.
+ * verbose if @verbose.
  */
 static int
 sendmessage(struct natstr *to, char *message, int verbose)

src/lib/commands/laun.c

@@ -124,7 +124,7 @@ laun(void)
 }
 
 /*
- * Launch anti-sat weapon PP.
+ * Launch anti-sat weapon @pp.
  * Return RET_OK if launched (even when missile explodes),
  * else RET_SYN or RET_FAIL.
  */
@@ -169,7 +169,7 @@ launch_as(struct plnstr *pp)
 }
 
 /*
- * Launch missile PP.
+ * Launch missile @pp.
  * Return RET_OK if launched (even when missile explodes),
  * else RET_SYN or RET_FAIL.
  */

src/lib/commands/rea.c

@@ -193,7 +193,7 @@ rea(void)
 }
 
 /*
- * Print first telegram in file FNAME.
+ * Print first telegram in file @fname.
  */
 int
 show_first_tel(char *fname)

src/lib/commands/xdump.c

@@ -39,7 +39,7 @@
 #include "xdump.h"
 
 /*
- * Is object P of type TYPE visible to the player?
+ * Is object @p of type @type visible to the player?
  * TODO: Fold this into interators.
  */
 static int
@@ -99,8 +99,8 @@ xdvisible(int type, void *p)
 }
 
 /*
- * Dump meta-data for items of type TYPE to XD.
+ * Dump meta-data for items of type @type to @xd.
- * Return RET_SYN when TYPE doesn't have meta-data, else RET_OK.
+ * Return RET_SYN when @type doesn't have meta-data, else RET_OK.
  */
 static int
 xdmeta(struct xdstr *xd, int type)
@@ -131,7 +131,7 @@ xdmeta(struct xdstr *xd, int type)
 }
 
 /*
- * Dump items of type TYPE selected by ARG to XD.
+ * Dump items of type @type selected by @arg to @xd.
  * Return RET_OK on success, RET_SYN on error.
  */
 static int

src/lib/common/btu.c

@@ -4,21 +4,21 @@
  *                Ken Stevens, Steve McClure, Markus Armbruster
  *
  *  Empire is free software: you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
+ *  it under the terms of the @GNU General Public License as published by
  *  the Free Software Foundation, either version 3 of the License, or
  *  (at your option) any later version.
  *
  *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  but @WITHOUT @ANY @WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  @MERCHANTABILITY or @FITNESS @FOR A @PARTICULAR @PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  @GNU General Public License for more details.
  *
- *  You should have received a copy of the GNU General Public License
+ *  You should have received a copy of the @GNU General Public License
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  *  ---
  *
- *  See files README, COPYING and CREDITS in the root of the source
+ *  See files @README, @COPYING and @CREDITS in the root of the source
  *  tree for related information and legal notices.  It is expected
  *  that future projects/authors will amend these files as needed.
  *
@@ -39,7 +39,7 @@
 #include "sect.h"
 
 /*
- * Return BTUs produced by CAP in ETU ETUs.
+ * Return BTUs produced by @cap in @etu ETUs.
  */
 static int
 accrued_btus(struct sctstr *cap, int etu)
@@ -70,7 +70,7 @@ accrued_btus(struct sctstr *cap, int etu)
 }
 
 /*
- * Grant nation NP the BTUs produced by its capital in ETU ETUs.
+ * Grant nation @np the BTUs produced by its capital in @etu ETUs.
  * Return whether it has a capital.
  */
 int

src/lib/common/cargo.c

@@ -72,7 +72,7 @@ static struct clink *clink[EF_NUKE + 1];
 static int nclink[EF_NUKE + 1];
 
 /*
- * Return pointer to CL's cargo list head for file type TYPE.
+ * Return pointer to @cl's cargo list head for file type @type.
  */
 static int *
 clink_headp(struct clink *cl, int type)
@@ -87,7 +87,7 @@ clink_headp(struct clink *cl, int type)
 }
 
 /*
- * Initialize cargo list link CL to empty.
+ * Initialize cargo list link @cl to empty.
  */
 static void
 clink_init(struct clink *cl)
@@ -100,7 +100,7 @@ clink_init(struct clink *cl)
 }
 
 /*
- * Check whether *UIDP is a valid uid for file type TYPE.
+ * Check whether *@uidp is a valid uid for file type @type.
  */
 static void
 clink_check1(int *uidp, int type)
@@ -110,7 +110,7 @@ clink_check1(int *uidp, int type)
 }
 
 /*
- * Check validity of cargo lists for file type TYPE.
+ * Check validity of cargo lists for file type @type.
  */
 static void
 clink_check(int type)
@@ -131,8 +131,8 @@ clink_check(int type)
 }
 
 /*
- * Add to CL's cargo list for type TYPE the uid UID.
+ * Add to @cl's cargo list for type @type the uid @uid.
- * UID must not be on any cargo list already.
+ * @uid must not be on any cargo list already.
  */
 static void
 clink_add(struct clink *cl, int type, int uid)
@@ -150,8 +150,8 @@ clink_add(struct clink *cl, int type, int uid)
 }
 
 /*
- * Remove from CL's cargo list for type TYPE the uid UID.
+ * Remove from @cl's cargo list for type @type the uid @uid.
- * UID must be on that cargo list.
+ * @uid must be on that cargo list.
  */
 static void
 clink_rem(struct clink *cl, int type, int uid)
@@ -176,8 +176,8 @@ clink_rem(struct clink *cl, int type, int uid)
 }
 
 /*
- * Update cargo lists for a change of CARGO's carrier.
+ * Update cargo lists for a change of @cargo's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Carrier is of type @type, and changes from uid @old to @new.
  * Negative uids mean no carrier.
  */
 void
@@ -192,8 +192,8 @@ unit_carrier_change(struct empobj *cargo, int type, int old, int new)
 }
 
 /*
- * Update cargo lists for a change of PP's carrier.
+ * Update cargo lists for a change of @pp's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Carrier is of type @type, and changes from uid @old to @new.
  * Negative uids mean no carrier.
  */
 void
@@ -203,8 +203,8 @@ pln_carrier_change(struct plnstr *pp, int type, int old, int new)
 }
 
 /*
- * Update cargo lists for a change of LP's carrier.
+ * Update cargo lists for a change of @lp's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Carrier is of type @type, and changes from uid @old to @new.
  * Negative uids mean no carrier.
  */
 void
@@ -214,8 +214,8 @@ lnd_carrier_change(struct lndstr *lp, int type, int old, int new)
 }
 
 /*
- * Update cargo lists for a change of NP's carrier.
+ * Update cargo lists for a change of @np's carrier.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Carrier is of type @type, and changes from uid @old to @new.
  * Negative uids mean no carrier.
  */
 void
@@ -272,7 +272,7 @@ unit_cargo_init(void)
 }
 
 /*
- * Resize clink[TYPE] to match ef_nelem(TYPE).
+ * Resize clink[@type] to match ef_nelem(@type).
  * Return 0 on success, -1 on error.
  * This is the struct empfile onresize callback for units.
  */
@@ -298,8 +298,8 @@ unit_onresize(int type)
 }
 
 /*
- * Find first unit on a carrier's cargo list for file type CARGO_TYPE.
+ * Find first unit on a carrier's cargo list for file type @cargo_type.
- * Search carrier UID of type TYPE.
+ * Search carrier @uid of type @type.
  * Return first unit's uid, or -1 if the carrier isn't carrying such
  * units.
  */
@@ -319,8 +319,8 @@ unit_cargo_first(int type, int uid, int cargo_type)
 }
 
 /*
- * Find the next unit on a cargo list for file type CARGO_TYPE.
+ * Find the next unit on a cargo list for file type @cargo_type.
- * Get the unit after CARGO_UID.
+ * Get the unit after @cargo_uid.
  * Return its uid, or -1 if there are no more on this list.
  */
 int
@@ -334,7 +334,7 @@ unit_cargo_next(int cargo_type, int cargo_uid)
 }
 
 /*
- * If SP carries planes, return the uid of the first one, else -1.
+ * If @sp carries planes, return the uid of the first one, else -1.
  */
 int
 pln_first_on_ship(struct shpstr *sp)
@@ -343,7 +343,7 @@ pln_first_on_ship(struct shpstr *sp)
 }
 
 /*
- * If LP carries planes, return the uid of the first one, else -1.
+ * If @lp carries planes, return the uid of the first one, else -1.
  */
 int
 pln_first_on_land(struct lndstr *lp)
@@ -352,7 +352,7 @@ pln_first_on_land(struct lndstr *lp)
 }
 
 /*
- * Find the next plane on the same carrier as plane#UID.
+ * Find the next plane on the same carrier as plane#@uid.
  * Return its uid, or -1 if there are no more.
  */
 int
@@ -362,7 +362,7 @@ pln_next_on_unit(int uid)
 }
 
 /*
- * If SP carries land units, return the uid of the first one, else -1.
+ * If @sp carries land units, return the uid of the first one, else -1.
  */
 int
 lnd_first_on_ship(struct shpstr *sp)
@@ -371,7 +371,7 @@ lnd_first_on_ship(struct shpstr *sp)
 }
 
 /*
- * If SP carries land units, return the uid of the first one, else -1.
+ * If @sp carries land units, return the uid of the first one, else -1.
  */
 int
 lnd_first_on_land(struct lndstr *lp)
@@ -380,7 +380,7 @@ lnd_first_on_land(struct lndstr *lp)
 }
 
 /*
- * Find the next land unit on the same carrier as land#UID.
+ * Find the next land unit on the same carrier as land#@uid.
  * Return its uid, or -1 if there are no more.
  */
 int
@@ -390,7 +390,7 @@ lnd_next_on_unit(int uid)
 }
 
 /*
- * If PP carries a nuke, return its uid, else -1.
+ * If @pp carries a nuke, return its uid, else -1.
  */
 int
 nuk_on_plane(struct plnstr *pp)
@@ -399,7 +399,7 @@ nuk_on_plane(struct plnstr *pp)
 }
 
 /*
- * Return length of a carrier's cargo list for file type CARGO_TYPE.
+ * Return length of a carrier's cargo list for file type @cargo_type.
  */
 int
 unit_cargo_count(int type, int uid, int cargo_type)
@@ -416,7 +416,7 @@ unit_cargo_count(int type, int uid, int cargo_type)
 }
 
 /*
- * Return number of land units loaded on SP.
+ * Return number of land units loaded on @sp.
  */
 int
 shp_nland(struct shpstr *sp)
@@ -425,7 +425,7 @@ shp_nland(struct shpstr *sp)
 }
 
 /*
- * Return number of land units loaded on LP.
+ * Return number of land units loaded on @lp.
  */
 int
 lnd_nland(struct lndstr *lp)

src/lib/common/cnumb.c

@@ -38,7 +38,7 @@
 #include "prototypes.h"
 
 /*
- * Search for a country matching CNTRY, return its number.
+ * Search for a country matching @cntry, return its number.
  * Return M_NOTFOUND if no such country exists, M_NOTUNIQUE if there
  * are several.
  */

src/lib/common/conftab.c

@@ -100,7 +100,7 @@ read_custom_tables(void)
 }
 
 /*
- * Read configuration table file FNAME.
+ * Read configuration table file @fname.
  * Return 0 on success, -1 on error.
  */
 static int

src/lib/common/ef_verify.c

@@ -404,7 +404,7 @@ ef_verify_config(void)
 /*
  * Verify game state is sane.
  * Correct minor problems, but write corrections to backing files only
- * if MAY_PUT is non-zero.
+ * if @may_put is non-zero.
  * Return -1 if uncorrected problems remain, else 0.
  */
 int

src/lib/common/file.c

@@ -64,8 +64,8 @@ static int ef_check(int);
 static unsigned ef_generation;
 
 /*
- * Open the file-backed table TYPE (EF_SECTOR, ...).
+ * Open the file-backed table @type (EF_SECTOR, ...).
- * HOW are flags to control operation.  Naturally, immutable flags are
+ * @how are flags to control operation.  Naturally, immutable flags are
  * not permitted.
  * The table must not be already open.
  * Return non-zero on success, zero on failure.
@@ -200,7 +200,7 @@ open_locked(char *name, int oflags, mode_t mode)
 }
 
 /*
- * Reallocate cache for table EP to hold COUNT slots.
+ * Reallocate cache for table @ep to hold @count slots.
  * The table must not be allocated statically.
  * The cache may still be unmapped.
  * If reallocation succeeds, any pointers obtained from ef_ptr()
@@ -234,7 +234,7 @@ ef_realloc_cache(struct empfile *ep, int count)
 }
 
 /*
- * Open the table TYPE, which is a view of a base table
+ * Open the table @type, which is a view of a base table
  * The table must not be already open.
  * Return non-zero on success, zero on failure.
  * Beware: views work only as long as the base table doesn't change size!
@@ -270,7 +270,7 @@ ef_open_view(int type)
 }
 
 /*
- * Close the open table TYPE (EF_SECTOR, ...).
+ * Close the open table @type (EF_SECTOR, ...).
  * Return non-zero on success, zero on failure.
  */
 int
@@ -308,7 +308,7 @@ ef_close(int type)
 }
 
 /*
- * Flush file-backed table TYPE (EF_SECTOR, ...) to its backing file.
+ * Flush file-backed table @type (EF_SECTOR, ...) to its backing file.
  * Do nothing if the table is privately mapped.
  * Update timestamps of written elements if table is EFF_TYPED.
  * Return non-zero on success, zero on failure.
@@ -340,7 +340,7 @@ ef_flush(int type)
 }
 
 /*
- * Return pointer to element ID in table TYPE if it exists, else NULL.
+ * Return pointer to element @id in table @type if it exists, else NULL.
  * The table must be fully cached, i.e. flags & EFF_MEM.
  * The caller is responsible for flushing changes he makes.
  */
@@ -360,9 +360,9 @@ ef_ptr(int type, int id)
 }
 
 /*
- * Read element ID from table TYPE into buffer INTO.
+ * Read element @id from table @type into buffer @into.
  * FIXME pass buffer size!
- * INTO is marked fresh with ef_mark_fresh().
+ * @into is marked fresh with ef_mark_fresh().
  * Return non-zero on success, zero on failure.
  */
 int
@@ -397,7 +397,7 @@ ef_read(int type, int id, void *into)
 }
 
 /*
- * Fill cache of file-backed EP with elements starting at ID.
+ * Fill cache of file-backed @ep with elements starting at @id.
  * If any were read, return their number.
  * Else return -1 and leave the cache unchanged.
  */
@@ -459,7 +459,7 @@ do_read(struct empfile *ep, void *buf, int id, int count)
 }
 
 /*
- * Write COUNT elements starting at ID from BUF to file-backed EP.
+ * Write @count elements starting at @id from @buf to file-backed @ep.
  * Update the timestamp if the table is EFF_TYPED.
  * Don't actually write if table is privately mapped.
  * Return 0 on success, -1 on error (file may be corrupt then).
@@ -523,14 +523,14 @@ do_write(struct empfile *ep, void *buf, int id, int count)
 }
 
 /*
- * Write element ID into table TYPE from buffer FROM.
+ * Write element @id into table @type from buffer @from.
  * FIXME pass buffer size!
- * Update timestamp in FROM if table is EFF_TYPED.
+ * Update timestamp in @from if table is EFF_TYPED.
  * If table is file-backed and not privately mapped, write through
  * cache straight to disk.
  * Cannot write beyond the end of fully cached table (flags & EFF_MEM).
  * Can write at the end of partially cached table.
- * FROM must be fresh; see ef_make_stale().
+ * @from must be fresh; see ef_make_stale().
  * Return non-zero on success, zero on failure.
  */
 int
@@ -577,9 +577,9 @@ ef_write(int type, int id, void *from)
 
 /*
  * Change element id.
- * BUF is an element of table TYPE.
+ * @buf is an element of table @type.
- * ID is its new element ID.
+ * @id is its new element ID.
- * If table is EFF_TYPED, change id and sequence number stored in BUF.
+ * If table is EFF_TYPED, change id and sequence number stored in @buf.
  * Else do nothing.
  */
 void
@@ -614,7 +614,7 @@ ef_typedstr_eq(struct ef_typedstr *a, struct ef_typedstr *b)
 }
 
 /*
- * Return sequence number of element ID in table EP.
+ * Return sequence number of element @id in table @ep.
  * Return zero if table is not EFF_TYPED (it has no sequence number
  * then).
  */
@@ -641,10 +641,10 @@ get_seqno(struct empfile *ep, int id)
 }
 
 /*
- * Increment sequence number in BUF, which is about to be written to EP.
+ * Increment sequence number in @buf, which is about to be written to @ep.
  * Do nothing if table is not EFF_TYPED (it has no sequence number
  * then).
- * Else, BUF's sequence number must match the one in EP's cache.  If
+ * Else, @buf's sequence number must match the one in @ep's cache.  If
  * it doesn't, we're about to clobber a previous write.
  */
 static void
@@ -700,7 +700,7 @@ must_be_fresh(struct empfile *ep, void *buf)
 }
 
 /*
- * Extend table TYPE by COUNT elements.
+ * Extend table @type by @count elements.
  * Any pointers obtained from ef_ptr() become invalid.
  * Return non-zero on success, zero on failure.
  */
@@ -772,9 +772,9 @@ do_extend(struct empfile *ep, int count)
 }
 
 /*
- * Initialize element ID for table TYPE in BUF.
+ * Initialize element @id for table @type in @buf.
  * FIXME pass buffer size!
- * BUF is marked fresh with ef_mark_fresh().
+ * @buf is marked fresh with ef_mark_fresh().
  */
 void
 ef_blank(int type, int id, void *buf)
@@ -794,7 +794,7 @@ ef_blank(int type, int id, void *buf)
 }
 
 /*
- * Initialize COUNT elements of EP in BUF, starting with element ID.
+ * Initialize @count elements of @ep in @buf, starting with element @id.
  */
 static void
 do_blank(struct empfile *ep, void *buf, int id, int count)
@@ -815,7 +815,7 @@ do_blank(struct empfile *ep, void *buf, int id, int count)
 }
 
 /*
- * Truncate table TYPE to COUNT elements.
+ * Truncate table @type to @count elements.
  * Any pointers obtained from ef_ptr() become invalid.
  * Return non-zero on success, zero on failure.
  */
@@ -903,7 +903,7 @@ ef_mtime(int type)
 }
 
 /*
- * Search for a table matching NAME, return its table type.
+ * Search for a table matching @name, return its table type.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.
  */
@@ -915,10 +915,10 @@ ef_byname(char *name)
 }
 
 /*
- * Search CHOICES[] for a table type matching NAME, return it.
+ * Search @choices[] for a table type matching @name, return it.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.
- * CHOICES[] must be terminated with a negative value.
+ * @choices[] must be terminated with a negative value.
  */
 int
 ef_byname_from(char *name, int choices[])
@@ -946,7 +946,7 @@ ef_byname_from(char *name, int choices[])
 }
 
 /*
- * Return name of table TYPE.  Always a single, short word.
+ * Return name of table @type.  Always a single, short word.
  */
 char *
 ef_nameof(int type)
@@ -957,7 +957,7 @@ ef_nameof(int type)
 }
 
 /*
- * Return "pretty" name of table TYPE.
+ * Return "pretty" name of table @type.
  */
 char *
 ef_nameof_pretty(int type)
@@ -976,8 +976,8 @@ ef_check(int type)
 }
 
 /*
- * Ensure table contains element ID.
+ * Ensure table contains element @id.
- * If necessary, extend it in steps of COUNT elements.
+ * If necessary, extend it in steps of @count elements.
  * Return non-zero on success, zero on failure.
  */
 int
@@ -994,7 +994,7 @@ ef_ensure_space(int type, int id, int count)
 }
 
 /*
- * Return maximum ID acceptable for table TYPE.
+ * Return maximum ID acceptable for table @type.
  * Assuming infinite memory and disk space.
  */
 int

src/lib/common/game.c

@@ -106,7 +106,7 @@ game_note_bsanct(void)
 }
 
 /*
- * Record an update in the game file, the current time is NOW.
+ * Record an update in the game file, the current time is @now.
  * This starts the Empire clock if it hasn't been started yet.
  */
 void
@@ -166,7 +166,7 @@ game_tick_tick(void)
 }
 
 /*
- * Set ETU timestamp *TICK to the current ETU time.
+ * Set ETU timestamp *@tick to the current ETU time.
  * Return by how many ETUs it was increased.
  */
 int
@@ -176,7 +176,7 @@ game_tick_to_now(short *tick)
 }
 
 /*
- * Set ETU timestamp *TICK to the ETU time recorded in the game struct.
+ * Set ETU timestamp *@tick to the ETU time recorded in the game struct.
  * The Empire clock is not updated.
  * Return by how many ETUs it was increased.
  */
@@ -193,7 +193,7 @@ game_step_a_tick(struct gamestr *game, short *tick)
 }
 
 /*
- * Reset ETU timestamp *TICK to zero.
+ * Reset ETU timestamp *@tick to zero.
  * Return how many ETUs it had left until etu_per_update.
  */
 int

src/lib/common/hours.c

@@ -45,8 +45,8 @@ static char *weekday(char *str, int *wday);
 static char *daytime_range(char *str, int *from_min, int *to_min);
 
 /*
- * Is week day WDAY (Sunday is 0) allowed by restriction DAYS?
+ * Is week day @wday (Sunday is 0) allowed by restriction @days?
- * If DAYS is not empty, it lists the allowed week day names.  See
+ * If @days is not empty, it lists the allowed week day names.  See
  * weekday() for syntax.
  */
 int
@@ -65,8 +65,8 @@ is_wday_allowed(int wday, char *days)
 }
 
 /*
- * Is day time DTIME (minutes since midnight) allowed by restriction TIMES?
+ * Is day time @dtime (minutes since midnight) allowed by restriction @times?
- * If TIMES is not empty, it lists the allowed day time ranges.  See
+ * If @times is not empty, it lists the allowed day time ranges.  See
  * daytime_range() for syntax.
  */
 int
@@ -99,8 +99,8 @@ gamehours(time_t t)
 }
 
 /*
- * Parse weekday name in STR.
+ * Parse weekday name in @str.
- * On success assign day number (Sunday is 0) to *WDAY and return
+ * On success assign day number (Sunday is 0) to *@wday and return
  * pointer to first character not parsed.
  * Else return NULL.
  * Abbreviated names are recognized, but not single characters.
@@ -135,8 +135,8 @@ weekday(char *str, int *wday)
 }
 
 /*
- * Parse day time in STR.
+ * Parse day time in @str.
- * On success store minutes since midnight in *MIN and return pointer
+ * On success store minutes since midnight in *@min and return pointer
  * to first character not parsed.
  * Else return NULL.
  * Time format is HOUR:MINUTE.  Initial whitespace is ignored.
@@ -170,8 +170,8 @@ daytime(char *str, int *min)
 }
 
 /*
- * Parse a day time range in STR.
+ * Parse a day time range in @str.
- * On success store minutes since midnight in *FROM and *TO, return
+ * On success store minutes since midnight in *@from and *@to, return
  * pointer to first character not parsed.
  * Else return NULL.
  * Format is HOUR:MINUTE-HOUR:MINUTE.  Initial whitespace is ignored.

src/lib/common/mailbox.c

@@ -49,7 +49,7 @@ mailbox(char *buf, natid cn)
 }
 
 /*
- * Create an empty telegram file named MBOX.
+ * Create an empty telegram file named @mbox.
  * Return 0 on success, -1 on failure.
  */
 int
@@ -66,8 +66,8 @@ mailbox_create(char *mbox)
 }
 
 /*
- * Read telegram header from FP into TEL.
+ * Read telegram header from @fp into @tel.
- * MBOX is the file name, it is used for logging errors.
+ * @mbox is the file name, it is used for logging errors.
  * Return 1 on success, 0 on EOF, -1 on error.
  */
 int
@@ -87,12 +87,12 @@ tel_read_header(FILE *fp, char *mbox, struct telstr *tel)
 }
 
 /*
- * Read telegram body from FP.
+ * Read telegram body from @fp.
- * MBOX is the file name, it is used for logging errors.
+ * @mbox is the file name, it is used for logging errors.
- * TEL is the header.
+ * @tel is the header.
- * Unless SINK is null, it is called like SINK(CHUNK, SZ, ARG) to
+ * Unless @sink is null, it is called like @sink(CHUNK, SZ, @arg) to
  * consume the body, chunk by chunk.  The chunks are UTF-8, and
- * CHUNK[SZ} is 0.  Reading fails when SINK() returns a negative
+ * CHUNK[SZ} is 0.  Reading fails when @sink() returns a negative
  * value.
  * Return 0 on success, -1 on failure.
  */

src/lib/common/nat.c

@@ -81,7 +81,7 @@ getrel(struct natstr *np, natid them)
 }
 
 /*
- * Return relations US has with THEM.
+ * Return relations @us has with @them.
  * Countries are considered allied to themselves.
  */
 int
@@ -157,8 +157,8 @@ influx(struct natstr *np)
 }
 
 /*
- * Initialize NATP for country #CNUM in status STAT.
+ * Initialize @natp for country #@cnum in status @stat.
- * STAT must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
+ * @stat must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
  * Also wipe realms and telegrams.
  */
 struct natstr *

src/lib/common/nstreval.c

@@ -43,8 +43,8 @@
 #include "optlist.h"
 
 /*
- * Initialize VAL to symbolic value for selector CA with index IDX.
+ * Initialize @val to symbolic value for selector @ca with index @idx.
- * Return VAL.
+ * Return @val.
  */
 struct valstr *
 nstr_mksymval(struct valstr *val, struct castr *ca, int idx)
@@ -60,17 +60,17 @@ nstr_mksymval(struct valstr *val, struct castr *ca, int idx)
 }
 
 /*
- * Evaluate VAL.
+ * Evaluate @val.
- * If VAL has category NSC_OFF, read the value from the context object
+ * If @val has category NSC_OFF, read the value from the context object
- * PTR, and translate it for country CNUM (coordinate system and
+ * @ptr, and translate it for country @cnum (coordinate system and
- * contact status).  No translation when CNUM is NATID_BAD.
+ * contact status).  No translation when @cnum is NATID_BAD.
- * PTR points to a context object of the type that was used to compile
+ * @ptr points to a context object of the type that was used to compile
  * the value.
- * Unless WANT is NSC_NOTYPE, coerce the value to promoted value type
+ * Unless @want is NSC_NOTYPE, coerce the value to promoted value type
- * WANT.  VAL must be coercible.
+ * @want.  @val must be coercible.
  * The result's type is promoted on success, NSC_NOTYPE on error.
  * In either case, the category is NSC_VAL.
- * Return VAL.
+ * Return @val.
  */
 struct valstr *
 nstr_eval(struct valstr *val, natid cnum, void *ptr, enum nsc_type want)
@@ -212,10 +212,10 @@ nstr_eval(struct valstr *val, natid cnum, void *ptr, enum nsc_type want)
 }
 
 /*
- * Promote VALTYPE.
+ * Promote @valtype.
- * If VALTYPE is an integer type, return NSC_LONG.
+ * If @valtype is an integer type, return NSC_LONG.
- * If VALTYPE is a floating-point type, return NSC_DOUBLE.
+ * If @valtype is a floating-point type, return NSC_DOUBLE.
- * If VALTYPE is a string type, return NSC_STRING.
+ * If @valtype is a string type, return NSC_STRING.
  */
 int
 nstr_promote(int valtype)

src/lib/common/pathfind.c

@@ -132,7 +132,7 @@ static double pf_sumcost;
 #endif	/* !PATH_FIND_STATS */
 
 #ifndef NDEBUG			/* silence "not used" warning */
-/* Is sector with uid UID open?  */
+/* Is sector with uid @uid open?  */
 static int
 pf_is_open(int uid)
 {
@@ -140,7 +140,7 @@ pf_is_open(int uid)
 }
 #endif
 
-/* Is sector with uid UID closed?  */
+/* Is sector with uid @uid closed?  */
 static int
 pf_is_closed(int uid)
 {
@@ -151,7 +151,7 @@ pf_is_closed(int uid)
     return pf_map[uid].visit > pf_visit;
 }
 
-/* Is sector with uid UID unvisited?  */
+/* Is sector with uid @uid unvisited?  */
 static int
 pf_is_unvisited(int uid)
 {
@@ -188,7 +188,7 @@ pf_check(void)
 #define pf_check() ((void)0)
 #endif
 
-/* Swap pf_heap's I-th and J-th elements.  */
+/* Swap pf_heap's @i-th and @j-th elements. */
 static void
 pf_heap_swap(int i, int j)
 {
@@ -203,7 +203,7 @@ pf_heap_swap(int i, int j)
     pf_map[pf_heap[j].uid].heapi = j;
 }
 
-/* Restore heap property after N-th element's cost increased.  */
+/* Restore heap property after @n-th element's cost increased. */
 static void
 pf_sift_down(int n)
 {
@@ -219,7 +219,7 @@ pf_sift_down(int n)
     }
 }
 
-/* Restore heap property after N-th element's cost decreased.  */
+/* Restore heap property after @n-th element's cost decreased. */
 static void
 pf_sift_up(int n)
 {
@@ -234,9 +234,9 @@ pf_sift_up(int n)
 }
 
 /*
- * Open the unvisited sector X,Y.
+ * Open the unvisited sector @x,@y.
- * UID is sector uid, it equals XYOFFSET(X,Y).
+ * @uid is sector uid, it equals XYOFFSET(@x,@y).
- * Cheapest path from source comes from direction DIR and has cost COST.
+ * Cheapest path from source comes from direction @dir and has cost @cost.
  */
 static void
 pf_open(int uid, coord x, coord y, int dir, double cost)
@@ -284,7 +284,7 @@ pf_close(void)
 /* silence "not used" warning */
 #ifdef PATH_FIND_DEBUG
 /*
- * Return cost from source to sector with uid UID.
+ * Return cost from source to sector with uid @uid.
  * It must be visited, i.e. open or closed.
  */
 static double
@@ -327,8 +327,8 @@ y_in_dir(coord y, int dir)
 
 /*
  * Set the current source and cost function.
- * SX,SY is the source.
+ * @sx,@sy is the source.
- * The cost to enter the sector with uid u is COST(ACTOR, u).
+ * The cost to enter the sector with uid u is @cost(@actor, u).
  * Negative value means the sector can't be entered.
  */
 static void
@@ -359,7 +359,7 @@ pf_set_source(coord sx, coord sy, natid actor, double (*cost)(natid, int))
 }
 
 /*
- * Find cheapest path from current source to DX,DY, return its cost.
+ * Find cheapest path from current source to @dx,@dy, return its cost.
  */
 double
 path_find_to(coord dx, coord dy)
@@ -413,10 +413,10 @@ path_find_to(coord dx, coord dy)
 }
 
 /*
- * Write route from SX,SY to DX,DY to BUF[BUFSIZ], return its length.
+ * Write route from @sx,@sy to @dx,@dy to @buf[@bufsiz], return its length.
- * If the route is longer than BUFSIZ-1 characters, it's truncated.
+ * If the route is longer than @bufsiz-1 characters, it's truncated.
  * You must compute path cost first, with path_find_to().
- * SX,SY must be on a shortest path from the current source to DX,DY.
+ * @sx,@sy must be on a shortest path from the current source to @dx,@dy.
  */
 size_t
 path_find_route(char *buf, size_t bufsz,
@@ -465,7 +465,7 @@ path_find_route(char *buf, size_t bufsz,
 }
 
 /*
- * Rotate BUF[BUFSZ] to put BUF[I] into BUF[0], and zero-terminate.
+ * Rotate @buf[@bufsz] to put @buf[@i] into @buf[0], and zero-terminate.
  */
 static char *
 bufrotate(char *buf, size_t bufsz, size_t i)
@@ -632,8 +632,8 @@ static double (*cost_tab[])(natid, int) = {
 };
 
 /*
- * Start finding paths from SX,SY.
+ * Start finding paths from @sx,@sy.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Use mobility costs for @actor and @mobtype.
  */
 void
 path_find_from(coord sx, coord sy, natid actor, int mobtype)
@@ -642,8 +642,8 @@ path_find_from(coord sx, coord sy, natid actor, int mobtype)
 }
 
 /*
- * Find cheapest path from SX,SY to DX,DY, return its mobility cost.
+ * Find cheapest path from @sx,@sy to @dx,@dy, return its mobility cost.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Use mobility costs for @actor and @mobtype.
  */
 double
 path_find(coord sx, coord sy, coord dx, coord dy, natid actor, int mobtype)

src/lib/common/rdsched.c

@@ -53,10 +53,10 @@ static int insert_update(time_t, time_t[], int, time_t);
 static int delete_update(time_t, time_t[], int);
 
 /*
- * Read update schedule from file FNAME.
+ * Read update schedule from file @fname.
- * Put the first N-1 updates after T0 into SCHED[] in ascending order,
+ * Put the first @n-1 updates after @t0 into @sched[] in ascending order,
  * terminated with a zero.
- * Use ANCHOR as initial anchor for anchor-relative times.
+ * Use @anchor as initial anchor for anchor-relative times.
  * Return 0 on success, -1 on failure.
  */
 int
@@ -97,10 +97,10 @@ read_schedule(char *fname, time_t sched[], int n, time_t t0, time_t anchor)
 }
 
 /*
- * Parse an update schedule directive from LINE.
+ * Parse an update schedule directive from @line.
- * Update SCHED[] and ANCHOR accordingly.
+ * Update @sched[] and @anchor accordingly.
- * SCHED[] holds the first N-1 updates after T0 in ascending order.
+ * @sched[] holds the first N-1 updates after @t0 in ascending order.
- * FNAME and LNO file name and line number for reporting errors.
+ * @fname and @lno file name and line number for reporting errors.
  */
 static int
 parse_schedule_line(char *line, time_t sched[], int n,
@@ -149,8 +149,8 @@ parse_schedule_line(char *line, time_t sched[], int n,
 }
 
 /*
- * Complain and return zero when T is bad, else return non-zero.
+ * Complain and return zero when @t is bad, else return non-zero.
- * FNAME and LNO file name and line number.
+ * @fname and @lno file name and line number.
  */
 static int
 time_ok(time_t t, char *fname, int lno)
@@ -163,8 +163,8 @@ time_ok(time_t t, char *fname, int lno)
 }
 
 /*
- * Parse a time from S into *T.
+ * Parse a time from @s into *@t.
- * *ANCHOR is the base for anchor-relative time.
+ * *@anchor is the base for anchor-relative time.
  * Return pointer to first character not parsed on success,
  * null pointer on failure.
  */
@@ -240,7 +240,7 @@ parse_time(time_t *t, char *s, time_t *anchor)
 }
 
 /*
- * Parse an every clause from S into *SECS.
+ * Parse an every clause from @s into *@secs.
  * Return pointer to first character not parsed on success,
  * null pointer on failure.
  */
@@ -263,8 +263,8 @@ parse_every(time_t *secs, char *s)
 }
 
 /*
- * Parse an until clause from S into *T.
+ * Parse an until clause from @s into *@t.
- * *ANCHOR is the base for anchor-relative time.
+ * *@anchor is the base for anchor-relative time.
  * Return pointer to first character not parsed on success,
  * null pointer on failure.
  */
@@ -281,8 +281,8 @@ parse_until(time_t *t, char *s, time_t *anchor)
 }
 
 /*
- * Parse an skip clause from S into *T.
+ * Parse an skip clause from @s into *@t.
- * *ANCHOR is the base for anchor-relative time.
+ * *@anchor is the base for anchor-relative time.
  * Return pointer to first character not parsed on success,
  * null pointer on failure.
  */
@@ -299,7 +299,7 @@ parse_skip(time_t *t, char *s, time_t *anchor)
 }
 
 /*
- * Return the index of the first update at or after T in SCHED[].
+ * Return the index of the first update at or after @t in @sched[].
  */
 static int
 find_update(time_t t, time_t sched[])
@@ -312,11 +312,11 @@ find_update(time_t t, time_t sched[])
 }
 
 /*
- * Insert update at T into SCHED[].
+ * Insert update at @t into @sched[].
- * SCHED[] holds the first N-1 updates after T0 in ascending order.
+ * @sched[] holds the first @n-1 updates after @t0 in ascending order.
- * If T is before T0 or outside game_days/game_hours, return -1.
+ * If @t is before @t0 or outside game_days/game_hours, return -1.
- * If there's no space for T in SCHED[], return N-1.
+ * If there's no space for @t in @sched[], return N-1.
- * Else insert T into SCHED[] and return its index in SCHED[].
+ * Else insert @t into @sched[] and return its index in @sched[].
  */
 static int
 insert_update(time_t t, time_t sched[], int n, time_t t0)
@@ -334,9 +334,9 @@ insert_update(time_t t, time_t sched[], int n, time_t t0)
 }
 
 /*
- * Delete update T from SCHED[].
+ * Delete update @t from @sched[].
- * SCHED[] holds N-1 updates in ascending order.
+ * @sched[] holds @n-1 updates in ascending order.
- * Return the index of the first update after T in SCHED[].
+ * Return the index of the first update after @t in @sched[].
  */
 static int
 delete_update(time_t t, time_t sched[], int n)

src/lib/common/stmtch.c

@@ -35,14 +35,14 @@
 #include "match.h"
 
 /*
- * Find element named NEEDLE in array HAYSTACK[], return its index.
+ * Find element named @needle in array @haystack[], return its index.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.
- * Each array element has a pointer to its name stored at offset OFFS.
+ * Each array element has a pointer to its name stored at offset @offs.
  * Search stops when this name is a null pointer.
  * It ignores elements with an empty name.
- * NEEDLE is compared to element names with mineq(NEEDLE, NAME).
+ * @needle is compared to element names with mineq(@needle, NAME).
- * SIZE gives the size of an array element.
+ * @size gives the size of an array element.
  */
 int
 stmtch(char *needle, void *haystack, ptrdiff_t offs, size_t size)
@@ -74,10 +74,10 @@ stmtch(char *needle, void *haystack, ptrdiff_t offs, size_t size)
 }
 
 /*
- * Compare A with B.
+ * Compare @a with @b.
- * Return ME_EXACT if they are the same, or A is a prefix of B
+ * Return ME_EXACT if they are the same, or @a is a prefix of @b
- * followed by a space in B.
+ * followed by a space in @b.
- * Return ME_PARTIAL if A is a prefix of B not followed by a space.
+ * Return ME_PARTIAL if @a is a prefix of @b not followed by a space.
  * Else return ME_MISMATCH.
  */
 int

src/lib/common/type.c

@@ -47,7 +47,7 @@
 #include "ship.h"
 
 /*
- * Return index of sector called NAME in dchr[], or M_NOTFOUND.
+ * Return index of sector called @name in dchr[], or M_NOTFOUND.
  */
 int
 sct_typematch(char *name)
@@ -62,7 +62,7 @@ sct_typematch(char *name)
 }
 
 /*
- * Search table TYPE for an element matching NAME, return its index.
+ * Search table @type for an element matching @name, return its index.
  * Accepts EF_BAD, but of course never finds anything then.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.

src/lib/common/xdump.c

@@ -80,13 +80,13 @@
 #include "xdump.h"
 
 /*
- * Initialize XD.
+ * Initialize @xd.
- * Translate dump for country CNUM, except when CNUM is NATID_BAD.
+ * Translate dump for country @cnum, except when @cnum is NATID_BAD.
- * If HUMAN, dump in human-readable format.
+ * If @human, dump in human-readable format.
- * If SLOPPY, try to cope with invalid data (may result in invalid
+ * If @sloppy, try to cope with invalid data (may result in invalid
  * dump).
- * Dump is to be delivered through callback PR.
+ * Dump is to be delivered through callback @pr.
- * Return XD.
+ * Return @xd.
  */
 struct xdstr *
 xdinit(struct xdstr *xd, natid cnum, int human, int sloppy,
@@ -101,11 +101,11 @@ xdinit(struct xdstr *xd, natid cnum, int human, int sloppy,
 }
 
 /*
- * Evaluate a attribute of an object into VAL, return VAL.
+ * Evaluate a attribute of an object into @val, return @val.
- * CA describes the attribute.
+ * @ca describes the attribute.
- * XD is the xdump descriptor.
+ * @xd is the xdump descriptor.
- * PTR points to the context object.
+ * @ptr points to the context object.
- * IDX is the index within the attribute.
+ * @idx is the index within the attribute.
  */
 static struct valstr *
 xdeval(struct valstr *val, struct xdstr *xd,
@@ -116,8 +116,8 @@ xdeval(struct valstr *val, struct xdstr *xd,
 }
 
 /*
- * Dump string STR to XD with funny characters escaped.
+ * Dump string @str to @xd with funny characters escaped.
- * Dump at most N characters.
+ * Dump at most @n characters.
  */
 static void
 xdpresc(struct xdstr *xd, char *str, size_t n)
@@ -140,8 +140,8 @@ xdpresc(struct xdstr *xd, char *str, size_t n)
 }
 
 /*
- * Dump VAL prefixed with SEP to XD, in machine readable format.
+ * Dump @val prefixed with @sep to @xd, in machine readable format.
- * VAL must be evaluated.
+ * @val must be evaluated.
  * Return " ".
  */
 static char *
@@ -175,8 +175,8 @@ xdprval_nosym(struct xdstr *xd, struct valstr *val, char *sep)
 }
 
 /*
- * Dump symbol with value KEY from symbol table TYPE to XD.
+ * Dump symbol with value @key from symbol table @type to @xd.
- * Prefix with SEP, return " ".
+ * Prefix with @sep, return " ".
  */
 static char *
 xdprsym(struct xdstr *xd, int key, int type, char *sep)
@@ -194,9 +194,9 @@ xdprsym(struct xdstr *xd, int key, int type, char *sep)
 }
 
 /*
- * Dump VAL prefixed with SEP to XD, return " ".
+ * Dump @val prefixed with @sep to @xd, return " ".
- * VAL must be evaluated.
+ * @val must be evaluated.
- * CA describes the field from which the value was fetched.
+ * @ca describes the field from which the value was fetched.
  */
 static char *
 xdprval_sym(struct xdstr *xd, struct valstr *val, struct castr *ca,
@@ -228,9 +228,9 @@ xdprval_sym(struct xdstr *xd, struct valstr *val, struct castr *ca,
 }
 
 /*
- * Dump field values of a context object to XD.
+ * Dump field values of a context object to @xd.
- * CA[] describes fields.
+ * @ca[] describes fields.
- * PTR points to context object.
+ * @ptr points to context object.
  */
 void
 xdflds(struct xdstr *xd, struct castr ca[], void *ptr)
@@ -254,8 +254,8 @@ xdflds(struct xdstr *xd, struct castr ca[], void *ptr)
 }
 
 /*
- * Dump header for dump NAME to XD.
+ * Dump header for dump @name to @xd.
- * If META, it's for the meta-data dump rather than the data dump.
+ * If @meta, it's for the meta-data dump rather than the data dump.
  */
 void
 xdhdr(struct xdstr *xd, char *name, int meta)
@@ -269,9 +269,9 @@ xdhdr(struct xdstr *xd, char *name, int meta)
 }
 
 /*
- * Dump column header to XD.
+ * Dump column header to @xd.
- * CA[] describes fields.
+ * @ca[] describes fields.
- * Does nothing unless XD is human-readable.
+ * Does nothing unless @xd is human-readable.
  */
 void
 xdcolhdr(struct xdstr *xd, struct castr ca[])

src/lib/common/xundump.c

@@ -96,7 +96,7 @@ static int xubody(FILE *);
 static int xutail(FILE *, struct castr *);
 
 /*
- * Does the code hardcode indexes for table TYPE?
+ * Does the code hardcode indexes for table @type?
  */
 static int
 have_hardcoded_indexes(int type)
@@ -106,7 +106,7 @@ have_hardcoded_indexes(int type)
 }
 
 /*
- * Okay to truncate table TYPE?
+ * Okay to truncate table @type?
  */
 static int
 may_truncate(int type)
@@ -115,7 +115,7 @@ may_truncate(int type)
 }
 
 /*
- * Is TYPE's 0-th selector a usable ID?
+ * Is @type's 0-th selector a usable ID?
  */
 static int
 ca0_is_id(int type)
@@ -126,7 +126,7 @@ ca0_is_id(int type)
 }
 
 /*
- * Can we fill in gaps in table TYPE?
+ * Can we fill in gaps in table @type?
  */
 static int
 can_fill_gaps(int type)
@@ -136,7 +136,7 @@ can_fill_gaps(int type)
 }
 
 /*
- * Is table TYPE's ID-th record OBJ redundant for xundump()
+ * Is table @type's @id-th record @obj redundant for xundump()
  */
 int
 xundump_redundant(int type, int id, void *obj)
@@ -194,9 +194,9 @@ tbl_end(void)
 }
 
 /*
- * Seek to current table's ID-th object.
+ * Seek to current table's @id-th object.
  * Extend the table if necessary.
- * Save ID in cur_id.
+ * Save @id in cur_id.
  * Return the object on success, NULL on failure.
  */
 static void *
@@ -219,7 +219,7 @@ tbl_seek(int id)
 }
 
 /*
- * Omit ID1..ID2-1.
+ * Omit @id1..@id2-1.
  * Reset the omitted objects to default state.
  */
 static void
@@ -241,7 +241,7 @@ omit_ids(int id1, int id2)
 }
 
 /*
- * Return the smallest non-omitted ID in ID1..ID2-1 if any, else -1.
+ * Return the smallest non-omitted ID in @id1..@id2-1 if any, else -1.
  */
 static int
 expected_id(int id1, int id2)
@@ -290,8 +290,8 @@ tbl_part_done(void)
 }
 
 /*
- * Get selector for field FLDNO.
+ * Get selector for field @fldno.
- * Assign the field's selector index to *IDX, unless it is null.
+ * Assign the field's selector index to *@idx, unless it is null.
  * Return the selector on success, null pointer on error.
  */
 static struct castr *
@@ -309,7 +309,7 @@ getfld(int fldno, int *idx)
 }
 
 /*
- * Find the field for selector CA with index IDX.
+ * Find the field for selector @ca with index @idx.
  * Return the field number if it exists, else -1.
  */
 static int
@@ -365,7 +365,7 @@ rowid(void)
 }
 
 /*
- * Find the field NAME with index IDX and value representable as long.
+ * Find the field @name with index @idx and value representable as long.
  * Return the field number if it exists, else -1.
  */
 static int
@@ -493,7 +493,7 @@ rowobj(void)
 }
 
 /*
- * Is a new value for field FLDNO required to match the old one?
+ * Is a new value for field @fldno required to match the old one?
  */
 static int
 fldval_must_match(int fldno)
@@ -511,7 +511,7 @@ fldval_must_match(int fldno)
 }
 
 /*
- * Set OBJ's field FLDNO to DBL.
+ * Set @obj's field @fldno to @dbl.
  * Return 0 on success, -1 on error.
  */
 static int
@@ -594,7 +594,7 @@ putnum(void *obj, int fldno, double dbl)
 }
 
 /*
- * Set obj's field FLDNO to STR.
+ * Set obj's field @fldno to @str.
  * Return 0 on success, -1 on error.
  */
 static int
@@ -685,7 +685,7 @@ putrow(void)
 }
 
 /*
- * Read and ignore field separators from FP.
+ * Read and ignore field separators from @fp.
  * Return first character that is not a field separator.
  */
 static int
@@ -707,8 +707,8 @@ skipfs(FILE *fp)
 }
 
 /*
- * Decode escape sequences in BUF.
+ * Decode escape sequences in @buf.
- * Return BUF on success, null pointer on failure.
+ * Return @buf on success, null pointer on failure.
  */
 static char *
 xuesc(char *buf)
@@ -733,8 +733,8 @@ xuesc(char *buf)
 }
 
 /*
- * Read an identifier from FP into BUF.
+ * Read an identifier from @fp into @buf.
- * BUF must have space for 1024 characters.
+ * @buf must have space for 1024 characters.
  * Return number of characters read on success, -1 on failure.
  */
 static int
@@ -749,9 +749,9 @@ getid(FILE *fp, char *buf)
 }
 
 /*
- * Try to read a field name from FP.
+ * Try to read a field name from @fp.
- * I is the field number, counting from zero.
+ * @i is the field number, counting from zero.
- * If a name is read, set fldca[I] and fldidx[I] for it, and update
+ * If a name is read, set fldca[@i] and fldidx[@i] for it, and update
  * caflds[].
  * Return 1 if a name or ... was read, 0 on end of line, -1 on error.
  */
@@ -814,8 +814,8 @@ xufldname(FILE *fp, int i)
 }
 
 /*
- * Try to read a field value from FP.
+ * Try to read a field value from @fp.
- * I is the field number, counting from zero.
+ * @i is the field number, counting from zero.
  * Return 1 if a value was read, 0 on end of line, -1 on error.
  */
 static int
@@ -891,8 +891,8 @@ xufld(FILE *fp, int i)
 }
 
 /*
- * Read fields from FP.
+ * Read fields from @fp.
- * Use PARSE() to read each field.
+ * Use @parse() to read each field.
  * Return number of fields read on success, -1 on error.
  */
 static int
@@ -915,9 +915,9 @@ xuflds(FILE *fp, int (*parse)(FILE *, int))
 }
 
 /*
- * Define the FLDNO-th field.
+ * Define the @fldno-th field.
- * If IDX is negative, define as selector NAME, else as NAME(IDX).
+ * If @idx is negative, define as selector @name, else as @name(@idx).
- * Set fldca[FLDNO] and fldidx[FLDNO] accordingly.
+ * Set fldca[@fldno] and fldidx[@fldno] accordingly.
  * Update caflds[].
  * Return 1 on success, -1 on error.
  */
@@ -993,7 +993,7 @@ chkflds(void)
 }
 
 /*
- * Set value of field FLDNO in current row to DBL.
+ * Set value of field @fldno in current row to @dbl.
  * Return 1 on success, -1 on error.
  */
 static int
@@ -1008,7 +1008,7 @@ setnum(int fldno, double dbl)
 }
 
 /*
- * Set value of field FLDNO in current row to STR.
+ * Set value of field @fldno in current row to @str.
  * Return 1 on success, -1 on error.
  */
 static int
@@ -1025,8 +1025,8 @@ setstr(int fldno, char *str)
 }
 
 /*
- * Resolve symbol name ID in table referred to by CA.
+ * Resolve symbol name @id in table referred to by @ca.
- * Use field number N for error messages.
+ * Use field number @n for error messages.
  * Return index in referred table on success, -1 on failure.
  */
 static int
@@ -1042,7 +1042,7 @@ xunsymbol(char *id, struct castr *ca, int n)
 
 /*
  * Map symbol index to symbol value.
- * CA is the table, and I is the index in it.
+ * @ca is the table, and @i is the index in it.
  */
 static int
 symval(struct castr *ca, int i)
@@ -1057,7 +1057,7 @@ symval(struct castr *ca, int i)
 }
 
 /*
- * Set value of field FLDNO in current object to value of symbol SYM.
+ * Set value of field @fldno in current object to value of symbol @sym.
  * Return 1 on success, -1 on error.
  */
 static int
@@ -1080,7 +1080,7 @@ setsym(int fldno, char *sym)
 }
 
 /*
- * Create an empty symbol set for field FLDNO in *SET.
+ * Create an empty symbol set for field @fldno in *@set.
  * Return 1 on success, -1 on error.
  */
 static int
@@ -1100,8 +1100,8 @@ mtsymset(int fldno, long *set)
 }
 
 /*
- * Add a symbol to a symbol set for field FLDNO in *SET.
+ * Add a symbol to a symbol set for field @fldno in *@set.
- * SYM is the name of the symbol to add.
+ * @sym is the name of the symbol to add.
  * Return 1 on success, -1 on error.
  */
 static int
@@ -1122,8 +1122,8 @@ add2symset(int fldno, long *set, char *sym)
 }
 
 /*
- * Read an xdump table header line from FP.
+ * Read an xdump table header line from @fp.
- * Expect header for EXPECTED_TABLE, unless it is EF_BAD.
+ * Expect header for @expected_table, unless it is EF_BAD.
  * Recognize header for machine- and human-readable syntax, and set
  * human accordingly.
  * Return table type on success, -2 on EOF before header, -1 on failure.
@@ -1171,8 +1171,8 @@ xuheader(FILE *fp, int expected_table)
 
 /*
  * Find fields in this xdump.
- * If reading human-readable syntax, read a field header line from FP.
+ * If reading human-readable syntax, read a field header line from @fp.
- * Else take fields from the table's selectors in CA[].
+ * Else take fields from the table's selectors in @ca[].
  * Set ellipsis, nflds, fldca[], fldidx[] and caflds[] accordingly.
  * Return 0 on success, -1 on failure.
  */
@@ -1215,9 +1215,9 @@ xufldhdr(FILE *fp, struct castr ca[])
 }
 
 /*
- * Read xdump footer from FP.
+ * Read xdump footer from @fp.
- * CA[] contains the table's selectors.
+ * @ca[] contains the table's selectors.
- * The body had RECS records.
+ * The body had @recs records.
  * Update cafldspp[] from caflds[].
  * Return 0 on success, -1 on failure.
  */
@@ -1251,12 +1251,12 @@ xufooter(FILE *fp, struct castr ca[], int recs)
 }
 
 /*
- * Read an xdump table from FP.
+ * Read an xdump table from @fp.
  * Both machine- and human-readable xdump syntax are recognized.
- * Expect table EXPECTED_TABLE, unless it is EF_BAD.
+ * Expect table @expected_table, unless it is EF_BAD.
  * Report errors to stderr.
- * Messages assume FP starts in the file FILE at line *PLNO.
+ * Messages assume @fp starts in the file @file at line *@plno.
- * Update *PLNO to reflect lines read from FP.
+ * Update *@plno to reflect lines read from @fp.
  * Return table type on success, -2 on EOF before header, -1 on failure.
  */
 int
@@ -1308,8 +1308,8 @@ xundump(FILE *fp, char *file, int *plno, int expected_table)
 }
 
 /*
- * Read the remainder of an xdump after the table header line from FP.
+ * Read the remainder of an xdump after the table header line from @fp.
- * CA[] contains the table's selectors.
+ * @ca[] contains the table's selectors.
  * Return 0 on success, -1 on failure.
  */
 static int
@@ -1332,7 +1332,7 @@ xutail(FILE *fp, struct castr *ca)
 }
 
 /*
- * Read the body of an xdump table from FP.
+ * Read the body of an xdump table from @fp.
  * Return number of rows read on success, -1 on failure.
  */
 static int

src/lib/common/xy.c

@@ -149,11 +149,11 @@ xydist_range(coord x, coord y, int dist, struct range *rp)
 }
 
 /*
- * Convert initial part of STR to normalized x-coordinate.
+ * Convert initial part of @str to normalized x-coordinate.
  * Return -1 on error.  This works, as normalized coordinates are
  * non-negative.
- * Assign pointer to first character after the coordinate to *END,
+ * Assign pointer to first character after the coordinate to *@end,
- * unless END is a null pointer.
+ * unless @end is a null pointer.
  */
 coord
 strtox(char *str, char **end)
@@ -168,11 +168,11 @@ strtox(char *str, char **end)
 }
 
 /*
- * Convert initial part of STR to normalized y-coordinate.
+ * Convert initial part of @str to normalized y-coordinate.
  * Return -1 on error.  This works, as normalized coordinates are
  * non-negative.
- * Assign pointer to first character after the coordinate to *END,
+ * Assign pointer to first character after the coordinate to *@end,
- * unless END is a null pointer.
+ * unless @end is a null pointer.
  */
 coord
 strtoy(char *str, char **end)

src/lib/empthread/io.c

@@ -105,9 +105,9 @@ io_open(int fd, int flags, int bufsize)
 }
 
 /*
- * Close IOP.
+ * Close @iop.
  * Flush output and wait for the client to close the connection.
- * Wait at most until DEADLINE.  (time_t)-1 means wait as long as it
+ * Wait at most until @deadline.  (time_t)-1 means wait as long as it
  * takes (no timeout).
  * Both the flush and the wait can be separately cut short by
  * empth_wakeup().  This is almost certainly not what you want.  If
@@ -161,10 +161,10 @@ io_timeout(struct timeval *timeout, time_t deadline)
 }
 
 /*
- * Read input from IOP and enqueue it.
+ * Read input from @iop and enqueue it.
- * Wait at most until DEADLINE for input to arrive.  (time_t)-1 means
+ * Wait at most until @deadline for input to arrive.  (time_t)-1 means
  * wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
  * A wait for input can be cut short by empth_wakeup().
  * Return number of bytes read on success, -1 on error.
  * In particular, return zero on timeout, early wakeup or EOF.  Use
@@ -224,10 +224,10 @@ io_outputwaiting(struct iop *iop)
 }
 
 /*
- * Write output queued in IOP.
+ * Write output queued in @iop.
- * Wait at most until DEADLINE for input to arrive.  (time_t)-1 means
+ * Wait at most until @deadline for input to arrive.  (time_t)-1 means
  * wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
  * A wait for output can be cut short by empth_wakeup().
  * Return number of bytes written on success, -1 on error.
  * In particular, return zero when nothing was written because the
@@ -280,11 +280,11 @@ io_output(struct iop *iop, time_t deadline)
 }
 
 /*
- * Write output queued in IOP if enough have been enqueued.
+ * Write output queued in @iop if enough have been enqueued.
  * Write if at least one buffer has been filled since the last write.
- * Wait at most until DEADLINE for output to be accepted.  (time_t)-1
+ * Wait at most until @deadline for output to be accepted.  (time_t)-1
  * means wait as long as it takes (no timeout).
- * Does not yield the processor when DEADLINE is zero.
+ * Does not yield the processor when @deadline is zero.
  * A wait for output can be cut short by empth_wakeup().
  * Return number of bytes written on success, -1 on error.
  * In particular, return zero when nothing was written because the
@@ -364,8 +364,8 @@ io_eof(struct iop *iop)
 }
 
 /*
- * Discard IOP's buffered input and set its EOF flag.
+ * Discard @iop's buffered input and set its EOF flag.
- * No more input can be read from IOP.
+ * No more input can be read from @iop.
  */
 void
 io_set_eof(struct iop *iop)

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).
+ * Round @val to nearest integer (on the average).
- * VAL's fractional part is chance to round up.
+ * @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.
+ * Interpret @fname relative to directory @dir.
- * Return FNAME if it is absolute, or DIR is null or empty.
+ * Return @fname if it is absolute, or @dir is null or empty.
- * Else return a malloc'ed string containing DIR/FNAME, or null
+ * 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
+ * This is exactly like fopen(), except @fname is interpreted relative
- * to DIR if that is neither null nor empty.
+ * 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.
+ * Parse user command in @buf.
- * BUF is UTF-8.
+ * @buf is UTF-8.
- * Command name and arguments are copied into SPACE[], whose size must
+ * Command name and arguments are copied into @space[], whose size must
- * be at least strlen(BUF) + 1.
+ * be at least strlen(@buf) + 1.
- * Set ARG[0] to the zero-terminated command name.
+ * Set @arg[0] to the zero-terminated command name.
- * Set ARG[1..N] to the zero-terminated arguments, where N is the
+ * Set @arg[1..N] to the zero-terminated arguments, where N is the
- * number of arguments.  Set ARG[N+1..127] to NULL.
+ * number of arguments.  Set @arg[N+1..127] to NULL.
- * Set TAIL[0..N] to beginning of ARG[0] in BUF[].
+ * Set @tail[0..N] to beginning of @arg[0] in @buf[].
- * If CONDP is not null, recognize conditional argument syntax, and
+ * If @condp is not null, recognize conditional argument syntax, and
- * set *CONDP to the conditional argument if present, else NULL.
+ * set *@condp to the conditional argument if present, else NULL.
- * If REDIR is not null, recognize redirection syntax, and set *REDIR
+ * 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,

src/lib/lwp/sel.c

@@ -121,7 +121,7 @@ lwpSleepFd(int fd, int mask, struct timeval *timeout)
 }
 
 /*
- * Wake up PROC if it is sleeping in lwpSleepFd().
+ * Wake up @proc if it is sleeping in lwpSleepFd().
  * Must be followed by lwpWakeupSleep() before the next lwpReschedule().
  */
 static void

src/lib/lwp/sig.c

@@ -55,7 +55,7 @@ static struct lwpProc *LwpSigWaiter;
 static void lwpCatchAwaitedSig(int);
 
 /*
- * Initialize waiting for signals in SET.
+ * Initialize waiting for signals in @set.
  */
 void
 lwpInitSigWait(sigset_t *set)
@@ -83,7 +83,7 @@ lwpCatchAwaitedSig(int sig)
 }
 
 /*
- * Test whether a signal from SET has been catched.
+ * Test whether a signal from @set has been catched.
  * If yes, delete that signal from the set of catched signals, and
  * return its number.
  * Else return 0.
@@ -107,8 +107,8 @@ lwpGetSig(sigset_t *set)
 }
 
 /*
- * Wait until a signal from SET arrives.
+ * Wait until a signal from @set arrives.
- * Assign its number to *SIG and return 0.
+ * Assign its number to *@sig and return 0.
  * If another thread is already waiting for signals, return EBUSY
  * without waiting.
  */

src/lib/player/accept.c

@@ -134,7 +134,7 @@ player_prev(struct player *lp)
 }
 
 /*
- * Return player in state PS_PLAYING for CNUM.
+ * Return player in state PS_PLAYING for @cnum.
  */
 struct player *
 getplayer(natid cnum)

src/lib/player/dispatch.c

@@ -55,9 +55,9 @@ int test_suite_prng_seed;
 
 /*
  * Execute command named by player->argp[0].
- * BUF is the raw UTF-8 command line.  It should have been passed to
+ * @buf is the raw UTF-8 command line.  It should have been passed to
  * parse() to set up player->argp.
- * If REDIR is not null, it's the command's redirection, in UTF-8.
+ * If @redir is not null, it's the command's redirection, in UTF-8.
  * Return -1 if the command is not unique or doesn't exist, else 0.
  */
 int

src/lib/player/empdis.c

@@ -59,7 +59,7 @@ static int player_commands_index = 0;
 static void disable_coms(void);
 
 /*
- * Get a command from the current player into COMBUFP[1024], in UTF-8.
+ * Get a command from the current player into @combufp[1024], in UTF-8.
  * This may block for input, yielding the processor.  Flush buffered
  * output when blocking, to make sure player sees the prompt.
  * Return command's byte length on success, -1 on error.

src/lib/player/player.c

@@ -202,7 +202,7 @@ status(void)
 }
 
 /*
- * Make all objects stale if ARG is one of the player's command arguments.
+ * Make all objects stale if @arg is one of the player's command arguments.
  * See ef_make_stale() for what "making stale" means.
  * Useful for functions that prompt for missing arguments.
  * These can yield the processor, so we'd like to call ef_make_stale()

src/lib/player/recvclient.c

@@ -43,7 +43,7 @@
  * Receive a line of input from the current player.
  * If the player's aborted flag is set, return -1 without receiving
  * input.
- * Else receive one line and store it in CMD[SIZE].
+ * Else receive one line and store it in @cmd[@size].
  * This may block for input, yielding the processor.  Flush buffered
  * output when blocking, to make sure player sees the prompt.
  * If the player's connection has the I/O error or EOF indicator set,

src/lib/subs/actofgod.c

@@ -70,17 +70,17 @@ report_god_gives(char *prefix, char *what, natid to)
 }
 
 /*
- * Report deity meddling with sector SP.
+ * Report deity meddling with sector @sp.
  * Print a message (always), send a bulletin to the sector owner and
  * report news (sometimes).
- * NAME names what is being changed in the sector.
+ * @name names what is being changed in the sector.
- * If CHANGE is zero, the meddling is a no-op (bulletin suppressed).
+ * If @change is zero, the meddling is a no-op (bulletin suppressed).
- * If CHANGE is negative, it's secret (bulletin suppressed).
+ * If @change is negative, it's secret (bulletin suppressed).
- * If a bulletin is sent, report N_AIDS news for positive GOODNESS,
+ * If a bulletin is sent, report N_AIDS news for positive @goodness,
- * N_HURTS news for negative GOODNESS
+ * N_HURTS news for negative @goodness
- * The bulletin's text is like "NAME of sector X,Y changed <how> by an
+ * The bulletin's text is like "@name of sector X,Y changed <how> by an
  * act of <deity>, where <deity> is the deity's name, and <how> comes
- * from formatting printf-style FMT with optional arguments.
+ * from formatting printf-style @fmt with optional arguments.
  */
 void
 divine_sct_change(struct sctstr *sp, char *name,
@@ -110,7 +110,7 @@ divine_sct_change(struct sctstr *sp, char *name,
 }
 
 /*
- * Report deity meddling with NP.
+ * Report deity meddling with @np.
  * Just like divine_sct_change(), only for nations.
  */
 void
@@ -138,7 +138,7 @@ divine_nat_change(struct natstr *np, char *name,
 }
 
 /*
- * Report deity meddling with UNIT.
+ * Report deity meddling with @unit.
  * Just like divine_sct_change(), only for ships, planes, land units,
  * nukes.
  */
@@ -232,8 +232,8 @@ divine_flag_change(struct empobj *unit, char *name,
 }
 
 /*
- * Report deity giving/taking commodities to/from WHOM.
+ * Report deity giving/taking commodities to/from @whom.
- * Give AMT of IP in PLACE.
+ * Give @amt of @ip in @place.
  */
 void
 report_divine_gift(natid whom, struct ichrstr *ip, int amt, char *place)

src/lib/subs/attsub.c

@@ -745,8 +745,8 @@ att_ask_offense(int combat_mode, struct combat *off, struct combat *def,
 }
 
 /*
- * Return path cost for ATTACKER to enter sector given by DEF.
+ * Return path cost for @attacker to enter sector given by @def.
- * MOBTYPE is a mobility type accepted by sector_mcost().
+ * @mobtype is a mobility type accepted by sector_mcost().
  */
 static double
 att_mobcost(natid attacker, struct combat *def, int mobtype)

src/lib/subs/bridgefall.c

@@ -49,8 +49,8 @@
 static void knockdown(struct sctstr *);
 
 /*
- * Is there support for a bridge at SP?
+ * Is there support for a bridge at @sp?
- * Ignore support coming from direction IGNORE_DIR.
+ * Ignore support coming from direction @ignore_dir.
  */
 int
 bridge_support_at(struct sctstr *sp, int ignore_dir)
@@ -78,10 +78,10 @@ bridge_support_at(struct sctstr *sp, int ignore_dir)
 }
 
 /*
- * Check bridges at and around SP after damage to SP.
+ * Check bridges at and around @sp after damage to @sp.
- * If SP is an inefficent bridge, splash it.
+ * If @sp is an inefficent bridge, splash it.
- * If SP can't support a bridge, splash unsupported adjacent bridges.
+ * If @sp can't support a bridge, splash unsupported adjacent bridges.
- * Write back splashed bridges, except for SP; writing that one is
+ * Write back splashed bridges, except for @sp; writing that one is
  * left to the caller.
  */
 void

src/lib/subs/coastal.c

@@ -92,8 +92,8 @@ coastal_land_to_sea(coord x, coord y)
 }
 
 /*
- * Compute coastal flags for a change of SP from OLDDES to NEWDES.
+ * Compute coastal flags for a change of @sp from @olddes to @newdes.
- * Update adjacent sectors, but don't touch SP.
+ * Update adjacent sectors, but don't touch @sp.
  */
 void
 set_coastal(struct sctstr *sp, int olddes, int newdes)

src/lib/subs/control.c

@@ -65,10 +65,10 @@ military_control(struct sctstr *sp)
 }
 
 /*
- * Ask user to confirm abandonment of sector SP, if any.
+ * Ask user to confirm abandonment of sector @sp, if any.
- * If removing AMNT commodities of type VTYPE and the land units in
+ * If removing @amnt commodities of type @vtype and the land units in
- * LIST would abandon their sector, ask the user to confirm.
+ * @list would abandon their sector, ask the user to confirm.
- * All land units in LIST must be in this sector.  LIST may be null.
+ * All land units in @list must be in this sector.  @list may be null.
  * Return zero when abandonment was declined, else non-zero.
  */
 int
@@ -91,10 +91,10 @@ abandon_askyn(struct sctstr *sp, i_type vtype, int amnt,
 }
 
 /*
- * Would removing this stuff from SP abandon it?
+ * Would removing this stuff from @sp abandon it?
- * Consider removal of AMNT commodities of type VTYPE and the land
+ * Consider removal of @amnt commodities of type @vtype and the land
- * units in LIST.
+ * units in @list.
- * All land units in LIST must be in this sector.  LIST may be null.
+ * All land units in @list must be in this sector.  @list may be null.
  */
 int
 would_abandon(struct sctstr *sp, i_type vtype, int amnt,

src/lib/subs/fortdef.c

@@ -146,7 +146,7 @@ dd(natid att, natid def_own, coord ax, coord ay, int noisy, int defending)
 }
 
 /*
- * Shall CN attempt to help FRIEND against FOE?
+ * Shall @cn attempt to help @friend against @foe?
  */
 int
 feels_like_helping(natid cn, natid friend, natid foe)

src/lib/subs/getele.c

@@ -40,8 +40,8 @@
 static int tilde_escape(char *s);
 
 /*
- * Read a telegram for RECIPIENT into BUF, in UTF-8.
+ * Read a telegram for @recipient into @buf, in UTF-8.
- * BUF must have space for MAXTELSIZE+1 characters.
+ * @buf must have space for MAXTELSIZE+1 characters.
  * Return telegram length, or -1 on error.
  */
 int

src/lib/subs/getstarg.c

@@ -38,9 +38,9 @@
 
 /*
  * Get string argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
- * Copy input to BUF[1024].
+ * Copy input to @buf[1024].
- * Return BUF on success, else NULL.
+ * Return @buf on success, else NULL.
  */
 char *
 getstarg(char *input, char *prompt, char *buf)

src/lib/subs/getstring.c

@@ -35,8 +35,8 @@
 #include "prototypes.h"
 
 /*
- * Print sub-prompt PROMPT, receive a line of input into BUF[1024].
+ * Print sub-prompt @prompt, receive a line of input into @buf[1024].
- * Return BUF on success, else NULL.
+ * Return @buf on success, else NULL.
  */
 char *
 getstring(char *prompt, char *buf)
@@ -48,8 +48,8 @@ getstring(char *prompt, char *buf)
 }
 
 /*
- * Print sub-prompt PROMPT, receive a line of UTF-8 input into BUF[1024].
+ * Print sub-prompt @prompt, receive a line of UTF-8 input into @buf[1024].
- * Return BUF on success, else NULL.
+ * Return @buf on success, else NULL.
  */
 char *
 ugetstring(char *prompt, char *buf)

src/lib/subs/landgun.c

@@ -78,7 +78,7 @@ landunitgun(int effic, int guns)
 }
 
 /*
- * Fire from fortress SP.
+ * Fire from fortress @sp.
  * Use ammo, resupply if necessary.
  * Return damage if the fortress fires, else -1.
  */
@@ -98,7 +98,7 @@ fort_fire(struct sctstr *sp)
 }
 
 /*
- * Fire from ship SP.
+ * Fire from ship @sp.
  * Use ammo, resupply if necessary.
  * Return damage if the ship fires, else -1.
  */
@@ -122,7 +122,7 @@ shp_fire(struct shpstr *sp)
 }
 
 /*
- * Drop depth-charges from ship SP.
+ * Drop depth-charges from ship @sp.
  * Use ammo, resupply if necessary.
  * Return damage if the ship drops depth-charges, else -1.
  */
@@ -144,7 +144,7 @@ shp_dchrg(struct shpstr *sp)
 }
 
 /*
- * Fire torpedo from ship SP.
+ * Fire torpedo from ship @sp.
  * Use ammo and mobility, resupply if necessary.
  * Return damage if the ship fires, else -1.
  */
@@ -166,7 +166,7 @@ shp_torp(struct shpstr *sp, int usemob)
 }
 
 /*
- * Fire from land unit LP.
+ * Fire from land unit @lp.
  * Use ammo, resupply if necessary.
  * Return damage if the land unit fires, else -1.
  */
@@ -203,7 +203,7 @@ lnd_fire(struct lndstr *lp)
 }
 
 /*
- * Sabotage with land unit LP.
+ * Sabotage with land unit @lp.
  * Use ammo.
  * Return damage if the land unit sabotages, else -1.
  */
@@ -228,7 +228,7 @@ lnd_sabo(struct lndstr *lp, short item[])
 }
 
 /*
- * Return number of guns ship SP can fire.
+ * Return number of guns ship @sp can fire.
  */
 int
 shp_usable_guns(struct shpstr *sp)
@@ -237,7 +237,7 @@ shp_usable_guns(struct shpstr *sp)
 }
 
 /*
- * Return effective firing range for range factor RNG at tech TLEV.
+ * Return effective firing range for range factor @rng at tech @tlev.
  */
 static double
 effrange(int rng, double tlev)
@@ -247,7 +247,7 @@ effrange(int rng, double tlev)
 }
 
 /*
- * Return firing range for sector SP.
+ * Return firing range for sector @sp.
  */
 double
 fortrange(struct sctstr *sp)
@@ -265,7 +265,7 @@ fortrange(struct sctstr *sp)
 }
 
 /*
- * Return firing range for ship SP.
+ * Return firing range for ship @sp.
  */
 double
 shp_fire_range(struct shpstr *sp)
@@ -274,7 +274,7 @@ shp_fire_range(struct shpstr *sp)
 }
 
 /*
- * Return torpedo range for ship SP.
+ * Return torpedo range for ship @sp.
  */
 double
 torprange(struct shpstr *sp)
@@ -284,7 +284,7 @@ torprange(struct shpstr *sp)
 }
 
 /*
- * Return hit chance for torpedo from ship SP at range RANGE.
+ * Return hit chance for torpedo from ship @sp at range @range.
  */
 double
 shp_torp_hitchance(struct shpstr *sp, int range)
@@ -293,7 +293,7 @@ shp_torp_hitchance(struct shpstr *sp, int range)
 }
 
 /*
- * Return firing range for land unit SP.
+ * Return firing range for land unit @sp.
  */
 double
 lnd_fire_range(struct lndstr *lp)

src/lib/subs/lndsub.c

@@ -489,7 +489,7 @@ lnd_sel(struct nstr_item *ni, struct emp_qelem *list)
 }
 
 /*
- * Append LP to LIST.
+ * Append @lp to @list.
  * Return the new list link.
  */
 struct ulist *
@@ -587,11 +587,11 @@ lnd_put_one(struct ulist *llp)
 }
 
 /*
- * Sweep landmines with engineers in LAND_LIST for ACTOR.
+ * Sweep landmines with engineers in @land_list for @actor.
- * All land units in LAND_LIST must be in the same sector.
+ * All land units in @land_list must be in the same sector.
- * If EXPLICIT is non-zero, this is for an explicit sweep command from
+ * If @explicit is non-zero, this is for an explicit sweep command from
  * a player.  Else it's an automatic "on the move" sweep.
- * If TAKEMOB is non-zero, require and charge mobility.
+ * If @takemob is non-zero, require and charge mobility.
  * Return non-zero when the land units should stop.
  */
 int
@@ -954,8 +954,8 @@ lnd_mobcost(struct lndstr *lp, struct sctstr *sp)
 
 /*
  * Ask user to confirm sector abandonment, if any.
- * All land units in LIST must be in the same sector.
+ * All land units in @list must be in the same sector.
- * If removing the land units in LIST would abandon their sector, ask
+ * If removing the land units in @list would abandon their sector, ask
  * the user to confirm.
  * Return zero when abandonment was declined, else non-zero.
  */
@@ -1132,8 +1132,8 @@ lnd_mar_gauntlet(struct emp_qelem *list, int interdict, natid actor)
 }
 
 /*
- * Fire land unit support against VICTIM for ATTACKER, at X,Y.
+ * Fire land unit support against @victim for @attacker, at @x,@y.
- * If DEFENDING, this is defensive support, else offensive support.
+ * If @defending, this is defensive support, else offensive support.
  * Return total damage.
  */
 int
@@ -1192,8 +1192,8 @@ lnd_can_attack(struct lndstr *lp)
 }
 
 /*
- * Increase fortification value of LP.
+ * Increase fortification value of @lp.
- * Fortification costs mobility.  Use up to MOB mobility.
+ * Fortification costs mobility.  Use up to @mob mobility.
  * Return actual fortification increase.
  */
 int
@@ -1226,7 +1226,7 @@ lnd_fortify(struct lndstr *lp, int mob)
 }
 
 /*
- * Is there a engineer unit at X,Y that can help nation CN?
+ * Is there a engineer unit at @x,@y that can help nation @cn?
  */
 static int
 has_helpful_engineer(coord x, coord y, natid cn)
@@ -1246,7 +1246,7 @@ has_helpful_engineer(coord x, coord y, natid cn)
 }
 
 /*
- * Set LP's tech to TLEV along with everything else that depends on it.
+ * Set @lp's tech to @tlev along with everything else that depends on it.
  */
 void
 lnd_set_tech(struct lndstr *lp, int tlev)

src/lib/subs/lostsub.c

@@ -41,7 +41,7 @@
 static int findlost(int, natid, int, coord, coord, int);
 
 /*
- * Record item ID of type TYPE changed owner from EXOWN to OWN at X, Y.
+ * Record item @id of type @type changed owner from @exown to @own at @x, @y.
  */
 void
 lost_and_found(int type, natid exown, natid own, int id, coord x, coord y)
@@ -87,8 +87,8 @@ makenotlost(int type, natid owner, int id, coord x, coord y)
 
 /*
  * Find a suitable slot in the lost file.
- * If a record for TYPE, OWNER, ID, X, Y exists, return its index.
+ * If a record for @type, @owner, @id, @x, @y exists, return its index.
- * Else if FREE is non-zero, return the index of an unused record.
+ * Else if @free is non-zero, return the index of an unused record.
  * Else return -1.
  */
 static int

src/lib/subs/maps.c

@@ -353,8 +353,8 @@ bmnxtsct(struct nstr_sect *np)
 }
 
 /*
- * Return character to use in maps for sector type TYPE owned by OWN.
+ * Return character to use in maps for sector type @type owned by @own.
- * If OWNER_OR_GOD, the map is for the sector's owner or a deity.
+ * If @owner_or_god, the map is for the sector's owner or a deity.
  */
 static char
 map_char(int type, natid own, int owner_or_god)

src/lib/subs/mission.c

@@ -233,8 +233,8 @@ def_support(coord x, coord y, natid victim, natid actee)
 }
 
 /*
- * Perform support missions in X,Y against VICTIM for ACTEE.
+ * Perform support missions in @x,@y against @victim for @actee.
- * MISSION is either MI_OSUPPORT or MI_DSUPPORT.
+ * @mission is either MI_OSUPPORT or MI_DSUPPORT.
  * Return total damage.
  */
 static int
@@ -747,7 +747,7 @@ mission_name(int mission)
 }
 
 /*
- * Maximum distance GP can perform its mission.
+ * Maximum distance @gp can perform its mission.
  * Note: this has nothing to do with the radius of the op-area.
  * oprange() governs where the unit *can* strike, the op-area governs
  * where the player wants it to strike.
@@ -773,7 +773,7 @@ oprange(struct empobj *gp)
 }
 
 /*
- * Does GP's mission op area cover X,Y?
+ * Does @gp's mission op area cover @x,@y?
  */
 int
 in_oparea(struct empobj *gp, coord x, coord y)

src/lib/subs/mtch.c

@@ -37,10 +37,10 @@
 #include "prototypes.h"
 
 /*
- * Search for COMMAND in COMS[], return its index.
+ * Search for @command in @coms[], return its index.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several, M_IGNORE if the command should be ignored.
- * Ignore commands that require more permissions than COMSTAT.
+ * Ignore commands that require more permissions than @comstat.
  */
 int
 comtch(char *command, struct cmndstr *coms, int comstat)

src/lib/subs/natarg.c

@@ -44,7 +44,7 @@
 
 /*
  * Get nation argument.
- * If ARG is not empty, use it, else prompt for input using PROMPT.
+ * If @arg is not empty, use it, else prompt for input using @prompt.
  * If no input is provided, return NULL.
  * If the argument identifies a country, return its getnatp() value.
  * Else complain and return NULL.
@@ -79,7 +79,7 @@ natargp(char *arg, char *prompt)
 
 /*
  * Get nation argument.
- * If ARG is not empty, use it, else prompt for input using PROMPT.
+ * If @arg is not empty, use it, else prompt for input using @prompt.
  * If no input is provided, return -1.
  * If the argument identifies a country, return its number.  getnatp()
  * can be assumed to succeed for this number.

src/lib/subs/nstr.c

@@ -52,11 +52,11 @@ static struct valstr *nstr_resolve_val(struct valstr *, int, struct castr *);
 static int nstr_optype(enum nsc_type, enum nsc_type);
 
 /*
- * Compile conditions into array NP[LEN].
+ * Compile conditions into array @np[@len].
  * Return number of conditions, or -1 on error.
- * It is an error if there are more than LEN conditions.
+ * It is an error if there are more than @len conditions.
- * TYPE is the context type, a file type.
+ * @type is the context type, a file type.
- * STR is the condition string, in Empire syntax, without the leading
+ * @str is the condition string, in Empire syntax, without the leading
  * '?'.
  */
 int
@@ -223,9 +223,9 @@ strnncmp(char *s1, size_t sz1, char *s2, size_t sz2)
      : (CANT_REACH(), 0))
 
 /*
- * Evaluate compiled conditions in array NP[NCOND].
+ * Evaluate compiled conditions in array @np[@ncond].
  * Return non-zero iff they are all true.
- * PTR points to a context object of the type that was used to compile
+ * @ptr points to a context object of the type that was used to compile
  * the conditions.
  */
 int
@@ -271,7 +271,7 @@ nstr_exec(struct nscstr *np, int ncond, void *ptr)
 }
 
 /*
- * Parse a value in STR into VAL.
+ * Parse a value in @str into @val.
  * Return a pointer to the first character after the value.
  * Value is either evaluated into NSC_STRING, NSC_DOUBLE or NSC_LONG,
  * or an identifier.
@@ -333,10 +333,10 @@ nstr_parse_val(char *str, struct valstr *val)
 }
 
 /*
- * Match VAL in table of selector descriptors CA, return index.
+ * Match @val in table of selector descriptors @ca, return index.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.
- * A VAL that is not an identifier doesn't match anything.  A null CA
+ * A @val that is not an identifier doesn't match anything.  A null @ca
  * is considered empty.
  */
 static int
@@ -358,10 +358,10 @@ nstr_match_ca(struct valstr *val, struct castr *ca)
 }
 
 /*
- * Is identifier VAL the name of the selector given by CA and IDX?
+ * Is identifier @val the name of the selector given by @ca and @idx?
- * Return non-zero if and only if IDX is non-negative and VAL is the
+ * Return non-zero if and only if @idx is non-negative and @val is the
- * name of CA[IDX].
+ * name of @ca[@idx].
- * IDX must have been obtained from nstr_match_ca(VAL, CA).
+ * @idx must have been obtained from nstr_match_ca(@val, @ca).
  */
 static int
 nstr_is_name_of_ca(struct valstr *val, struct castr *ca, int idx)
@@ -373,8 +373,8 @@ nstr_is_name_of_ca(struct valstr *val, struct castr *ca, int idx)
 
 /*
  * Do we have two comparable selectors?
- * Check selector descriptors CA[LFT_IDX] (unless LFT_IDX is negative)
+ * Check selector descriptors @ca[@lft_idx] (unless @lft_idx is negative)
- * and CA[RGT_IDX] (unless RGT_IDX is negative).  CA may be null when
+ * and @ca[@rgt_idx] (unless @rgt_idx is negative).  @ca may be null when
  * both are negative.
  */
 static int
@@ -389,9 +389,9 @@ nstr_ca_comparable(struct castr *ca, int lft_idx, int rgt_idx)
 }
 
 /*
- * Match VAL in a selector's values, return its (non-negative) value.
+ * Match @val in a selector's values, return its (non-negative) value.
- * Match values of selector descriptor CA[IDX], provided IDX is not
+ * Match values of selector descriptor @ca[@idx], provided @idx is not
- * negative.  CA may be null when IDX is negative.
+ * negative.  @ca may be null when @idx is negative.
  * Return M_NOTFOUND if there are no matches, M_NOTUNIQUE if there are
  * several.
  */
@@ -419,10 +419,10 @@ nstr_match_val(struct valstr *val, struct castr *ca, int idx)
 }
 
 /*
- * Change VAL to resolve identifier to selector.
+ * Change @val to resolve identifier to selector.
- * Return VAL on success, NULL on error.
+ * Return @val on success, NULL on error.
- * No change if VAL is not an identifier.
+ * No change if @val is not an identifier.
- * Else change VAL into symbolic value for selector CA[IDX] if IDX >=
+ * Else change @val into symbolic value for selector @ca[@idx] if @idx >=
  * 0, and error if not.
  */
 static struct valstr *
@@ -463,10 +463,10 @@ nstr_resolve_id(struct valstr *val, struct castr *ca, int idx)
 }
 
 /*
- * Change VAL to resolve identifier to value SELVAL for selector CA.
+ * Change @val to resolve identifier to value @selval for selector @ca.
- * Return VAL.
+ * Return @val.
- * VAL must be an identifier, and SELVAL must have been obtained from
+ * @val must be an identifier, and @selval must have been obtained from
- * nstr_match_val(VAL, CA0, IDX), where CA = &CA0[IDX].
+ * nstr_match_val(@val, CA0, @idx), where @ca = &CA0[@IDX].
  */
 static struct valstr *
 nstr_resolve_val(struct valstr *val, int selval, struct castr *ca)
@@ -500,7 +500,7 @@ nstr_resolve_val(struct valstr *val, int selval, struct castr *ca)
 }
 
 /*
- * Return operator type for operand types LFT, RGT.
+ * Return operator type for operand types @lft, @rgt.
  */
 static int
 nstr_optype(enum nsc_type lft, enum nsc_type rgt)
@@ -517,10 +517,10 @@ nstr_optype(enum nsc_type lft, enum nsc_type rgt)
 }
 
 /*
- * Compile a value in STR into VAL.
+ * Compile a value in @str into @val.
  * Return a pointer to the first character after the value on success,
  * NULL on error.
- * TYPE is the context type, a file type.
+ * @type is the context type, a file type.
  */
 char *
 nstr_comp_val(char *str, struct valstr *val, int type)

src/lib/subs/paths.c

@@ -66,8 +66,8 @@ direrr(char *stop_msg, char *view_msg, char *map_msg)
 }
 
 /*
- * Map direction DIR to a direction index DIR_STOP..DIR_LAST.
+ * Map direction @dir to a direction index DIR_STOP..DIR_LAST.
- * DIR must be a valid direction.
+ * @dir must be a valid direction.
  */
 int
 diridx(char dir)

src/lib/subs/plnsub.c

@@ -59,12 +59,12 @@ static int inc_shp_nplane(struct plnstr *, int *, int *, int *);
 
 /*
  * Get planes and escorts argument.
- * Read planes into *NI_BOMB, and (optional) escorts into *NI_ESC.
+ * Read planes into *@ni_bomb, and (optional) escorts into *@ni_esc.
- * If INPUT_BOMB is not empty, use it, else prompt for more input.
+ * If @input_bomb is not empty, use it, else prompt for more input.
- * Same for INPUT_ESC.
+ * Same for @input_esc.
- * If we got a plane argument, initialize *NI_BOMB and *NI_ESC, and
+ * If we got a plane argument, initialize *@ni_bomb and *@ni_esc, and
  * return 0.
- * Else return -1 (*NI_BOMB and *NI_ESC may be modified).
+ * Else return -1 (*@ni_bomb and *@ni_esc may be modified).
  */
 int
 get_planes(struct nstr_item *ni_bomb, struct nstr_item *ni_esc,
@@ -82,11 +82,11 @@ get_planes(struct nstr_item *ni_bomb, struct nstr_item *ni_esc,
 
 /*
  * Get assembly point argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
- * If this yields a valid assembly point, read it into *AP_SECT and
+ * If this yields a valid assembly point, read it into *@ap_sect and
- * return AP_SECT.
+ * return @ap_sect.
  * Else complain and return NULL.
- * *AP_SECT and BUF[1024] may be modified in either case.
+ * *@ap_sect and @buf[1024] may be modified in either case.
  */
 struct sctstr *
 get_assembly_point(char *input, struct sctstr *ap_sect, char *buf)
@@ -120,10 +120,10 @@ get_assembly_point(char *input, struct sctstr *ap_sect, char *buf)
 }
 
 /*
- * Find out whether planes can fly one-way to X,Y.
+ * Find out whether planes can fly one-way to @x,@y.
  * Offer the player any carriers there.  If he chooses one, read it
- * into TARGET->ship.  Else read the target sector into TARGET->sect.
+ * into @target->ship.  Else read the target sector into @target->sect.
- * If planes can land there, set required plane flags in *FLAGSP, and
+ * If planes can land there, set required plane flags in *@flagsp, and
  * return 0.  Else return -1.
  */
 int
@@ -369,13 +369,13 @@ pln_mine(struct emp_qelem *list, coord tx, coord ty)
 }
 
 /*
- * Has PP's type capabilities satisfying WANTFLAGS and NOWANTFLAGS?
+ * Has @pp's type capabilities satisfying @wantflags and @nowantflags?
  * A plane type is capable unless
- * - it lacks all of the P_B, P_T in WANTFLAGS, or
+ * - it lacks all of the P_B, P_T in @wantflags, or
- * - it lacks all of the P_F, P_ESC in WANTFLAGS, or
+ * - it lacks all of the P_F, P_ESC in @wantflags, or
- * - it lacks all of the P_E, P_L, P_K in WANTFLAGS, or
+ * - it lacks all of the P_E, P_L, P_K in @wantflags, or
- * - it lacks any of the other capabilities in WANTFLAGS, or
+ * - it lacks any of the other capabilities in @wantflags, or
- * - it has any of the capabilities in NOWANTFLAGS.
+ * - it has any of the capabilities in @nowantflags.
  */
 int
 pln_capable(struct plnstr *pp, int wantflags, int nowantflags)
@@ -410,7 +410,7 @@ pln_capable(struct plnstr *pp, int wantflags, int nowantflags)
 }
 
 /*
- * Return union of capabilities of planes in LIST.
+ * Return union of capabilities of planes in @list.
  */
 int
 pln_caps(struct emp_qelem *list)
@@ -429,10 +429,10 @@ pln_caps(struct emp_qelem *list)
 }
 
 /*
- * Find plane types that can operate from carrier SP.
+ * Find plane types that can operate from carrier @sp.
- * If MSL find missile types, else non-missile types.
+ * If @msl find missile types, else non-missile types.
  * Return a combination of P_L, P_K, P_E.
- * It's zero if SP can't support air operations due to its type or
+ * It's zero if @sp can't support air operations due to its type or
  * state (low efficiency).
  */
 int
@@ -837,9 +837,9 @@ pln_put1(struct plist *plp)
 }
 
 /*
- * Can a carrier of SP's type carry this load of planes?
+ * Can a carrier of @sp's type carry this load of planes?
- * The load consists of N planes, of which NCH are choppers, NXL
+ * The load consists of @n planes, of which @nch are choppers, @nxl
- * xlight, NMSL light missiles, and the rest are light fixed-wing
+ * xlight, @nmsl light missiles, and the rest are light fixed-wing
  * planes.
  */
 static int
@@ -860,10 +860,10 @@ ship_can_carry(struct shpstr *sp, int n, int nch, int nxl, int nmsl)
 }
 
 /*
- * Increment carrier plane counters for PP.
+ * Increment carrier plane counters for @pp.
- * If it's a chopper, increment *NCH.
+ * If it's a chopper, increment *@nch.
- * Else, if it's x-light, increment *NXL.
+ * Else, if it's x-light, increment *@nxl.
- * Else, if it's a light missile, increment *MSL.
+ * Else, if it's a light missile, increment *@msl.
  * Return non-zero if it's a chopper, x-light or light.
  */
 static int
@@ -883,7 +883,7 @@ inc_shp_nplane(struct plnstr *pp, int *nch, int *nxl, int *nmsl)
 }
 
 /*
- * Can PP be loaded on a ship of SP's type?
+ * Can @pp be loaded on a ship of @sp's type?
  */
 int
 could_be_on_ship(struct plnstr *pp, struct shpstr *sp)
@@ -1102,7 +1102,7 @@ pln_is_in_orbit(struct plnstr *pp)
 }
 
 /*
- * Set PP's tech to TLEV along with everything else that depends on it.
+ * Set @pp's tech to @tlev along with everything else that depends on it.
  */
 void
 pln_set_tech(struct plnstr *pp, int tlev)

src/lib/subs/pr.c

@@ -70,7 +70,7 @@ static void player_output_some(void);
 
 /*
  * Print to current player similar to printf().
- * Use printf-style FORMAT with the optional arguments.
+ * Use printf-style @format with the optional arguments.
  * Note: `to print' without further qualifications means sending
  * C_DATA text.
  */
@@ -92,7 +92,7 @@ pr(char *format, ...)
 }
 
 /*
- * Print UTF-8 text BUF to current player.
+ * Print UTF-8 text @buf to current player.
  */
 void
 uprnf(char *buf)
@@ -109,8 +109,8 @@ uprnf(char *buf)
 }
 
 /*
- * Send some text to P with id ID, line-buffered.
+ * Send some text to @p with id @id, line-buffered.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
  * arguments.  It is assumed to be already user text.  Plain ASCII and
  * text received from the same player are fine, for anything else the
  * caller has to deal with output filtering.
@@ -134,8 +134,8 @@ pr_id(struct player *p, int id, char *format, ...)
 }
 
 /*
- * Send C_FLASH text to PL.
+ * Send C_FLASH text to @pl.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
  * arguments.  It is assumed to be UTF-8.
  * Initiate an output queue flush, but do not wait for it to complete.
  */
@@ -157,8 +157,8 @@ pr_flash(struct player *pl, char *format, ...)
 }
 
 /*
- * Send C_INFORM text to PL.
+ * Send C_INFORM text to @pl.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
  * arguments.  It is assumed to be plain ASCII.
  * Initiate an output queue flush, but do not wait for it to complete.
  */
@@ -179,7 +179,7 @@ pr_inform(struct player *pl, char *format, ...)
 
 /*
  * Send C_FLASH text to everyone.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
  * arguments.  It is assumed to be plain ASCII.
  * Prefix text it with a header suitable for broadcast from deity.
  * Initiate an output queue flush, but do not wait for it to complete.
@@ -211,8 +211,8 @@ pr_wall(char *format, ...)
 }
 
 /*
- * Send ID text BUF to PL, line-buffered.
+ * Send @id text @buf to @pl, line-buffered.
- * BUF is user text.
+ * @buf is user text.
  * If a partial line with different id is buffered, terminate it with
  * a newline first.
  */
@@ -250,7 +250,7 @@ pr_player(struct player *pl, int id, char *buf)
 }
 
 /*
- * Send ID text BUF to PL, line-buffered.
+ * Send @id text @buf to @pl, line-buffered.
  * This function translates from normal text to user text.
  * If a partial line with different id is buffered, terminate it with
  * a newline first.
@@ -305,7 +305,7 @@ upr_player(struct player *pl, int id, char *buf)
 }
 
 /*
- * Send id N to PL.
+ * Send id @n to @pl.
  * This runs always at the beginning of a line.
  */
 static void
@@ -336,8 +336,8 @@ player_output_some(void)
 }
 
 /*
- * Send redirection request REDIR to the current player.
+ * Send redirection request @redir to the current player.
- * REDIR is UTF-8, but non-ASCII characters can occur only if the
+ * @redir is UTF-8, but non-ASCII characters can occur only if the
  * player sent them.  Therefore, it is also user text.
  */
 void
@@ -347,8 +347,8 @@ prredir(char *redir)
 }
 
 /*
- * Send script execute request FILE to the current player.
+ * Send script execute request @file to the current player.
- * FILE is UTF-8, but non-ASCII characters can occur only if the
+ * @file is UTF-8, but non-ASCII characters can occur only if the
  * player sent them.  Therefore, it is also user text.
  */
 void
@@ -368,11 +368,11 @@ prprompt(int min, int btu)
 
 /*
  * Prompt for a line of non-command input.
- * Send C_FLUSH prompt PROMPT to the current player.
+ * Send C_FLUSH prompt @prompt to the current player.
- * Read a line of input into BUF[SIZE] and convert it to ASCII.
+ * Read a line of input into @buf[@size] and convert it to ASCII.
  * This may block for input, yielding the processor.  Flush buffered
  * output when blocking, to make sure player sees the prompt.
- * Return number of bytes in BUF[], not counting the terminating 0,
+ * Return number of bytes in @buf[], not counting the terminating 0,
  * or -1 on error.
  */
 int
@@ -396,12 +396,12 @@ prmptrd(char *prompt, char *buf, int size)
 
 /*
  * Prompt for a line of non-command, UTF-8 input.
- * Send C_FLUSH prompt PROMPT to the current player.
+ * Send C_FLUSH prompt @prompt to the current player.
- * Read a line of input into BUF[SIZE], replacing funny characters by
+ * Read a line of input into @buf[@size], replacing funny characters by
  * '?'.  The result is UTF-8.
  * This may block for input, yielding the processor.  Flush buffered
  * output when blocking, to make sure player sees the prompt.
- * Return number of bytes in BUF[], not counting the terminating 0,
+ * Return number of bytes in @buf[], not counting the terminating 0,
  * or -1 on error.
  */
 int
@@ -436,8 +436,8 @@ prdate(void)
 }
 
 /*
- * Print coordinates X, Y.
+ * Print coordinates @x, @y.
- * FORMAT must be a printf-style format string that converts exactly
+ * @format must be a printf-style format string that converts exactly
  * two int values.
  */
 void
@@ -462,11 +462,11 @@ pr_beep(void)
 }
 
 /*
- * Print complete lines to country CN similar to printf().
+ * Print complete lines to country @cn similar to printf().
- * Use printf-style FORMAT with the optional arguments.  FORMAT must
+ * Use printf-style @format with the optional arguments.  @format must
  * end with '\n'.
- * If CN is zero, don't print anything.
+ * If @cn is zero, don't print anything.
- * Else, if CN is the current player and we're not in the update,
+ * Else, if @cn is the current player and we're not in the update,
  * print just like pr().  Else print into a bulletin.
  * Because printing like pr() requires normal text, and bulletins
  * require user text, only plain ASCII is allowed.
@@ -490,11 +490,11 @@ mpr(int cn, char *format, ...)
 }
 
 /*
- * Copy SRC without funny characters to DST.
+ * Copy @src without funny characters to @dst.
  * Drop control characters, except for '\t'.
  * Replace non-ASCII characters by '?'.
- * Return length of DST.
+ * Return length of @dst.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * @dst must have space.  If it overlaps @src, then @dst <= @src must
  * hold.
  */
 size_t
@@ -518,11 +518,11 @@ copy_ascii_no_funny(char *dst, char *src)
 }
 
 /*
- * Copy UTF-8 SRC without funny characters to DST.
+ * Copy UTF-8 @src without funny characters to @dst.
  * Drop control characters, except for '\t'.
  * FIXME Replace malformed UTF-8 sequences by '?'.
- * Return byte length of DST.
+ * Return byte length of @dst.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * @dst must have space.  If it overlaps @src, then @dst <= @src must
  * hold.
  */
 size_t
@@ -545,11 +545,11 @@ copy_utf8_no_funny(char *dst, char *src)
 }
 
 /*
- * Copy UTF-8 SRC without funny characters to ASCII DST.
+ * Copy UTF-8 @src without funny characters to ASCII @dst.
  * Drop control characters, except for '\t'.
  * Replace non-ASCII characters by '?'.
- * Return length of DST.
+ * Return length of @dst.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * @dst must have space.  If it overlaps @src, then @dst <= @src must
  * hold.
  */
 size_t
@@ -576,8 +576,8 @@ copy_utf8_to_ascii_no_funny(char *dst, char *src)
 }
 
 /*
- * Return byte-index of the N-th UTF-8 character in UTF-8 string S.
+ * Return byte-index of the @n-th UTF-8 character in UTF-8 string @s.
- * If S doesn't have that many characters, return its length instead.
+ * If @s doesn't have that many characters, return its length instead.
  */
 int
 ufindpfx(char *s, int n)

src/lib/subs/radmap.c

@@ -59,9 +59,9 @@ static signed char **vis;
 static signed char *visbuf;
 
 /*
- * Draw a radar map for radar at CX,CY.
+ * Draw a radar map for radar at @cx,@cy.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
+ * @eff is the radar's efficiency, @tlev its tech level, @spy its power.
- * Submarines are detected at fraction SEESUB of the range.
+ * Submarines are detected at fraction @seesub of the range.
  */
 void
 radmap(int cx, int cy, int eff, double tlev, int spy, double seesub)
@@ -160,9 +160,9 @@ radmap(int cx, int cy, int eff, double tlev, int spy, double seesub)
 }
 
 /*
- * Return distance from left edge of R to X.
+ * Return distance from left edge of @r to @x.
  * Value is between 0 (inclusive) and WORLD_X (exclusive).
- * X must be normalized.
+ * @x must be normalized.
  */
 int
 deltx(struct range *r, coord x)
@@ -173,9 +173,9 @@ deltx(struct range *r, coord x)
 }
 
 /*
- * Return distance from top edge of R to Y.
+ * Return distance from top edge of @r to @y.
  * Value is between 0 (inclusive) and WORLD_Y (exclusive).
- * Y must be normalized.
+ * @y must be normalized.
  */
 int
 delty(struct range *r, coord y)
@@ -186,8 +186,8 @@ delty(struct range *r, coord y)
 }
 
 /*
- * Update OWNER's bmap for radar at CX,CY.
+ * Update @owner's bmap for radar at @cx,@cy.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
+ * @eff is the radar's efficiency, @tlev its tech level, @spy its power.
  */
 void
 rad_map_set(natid owner, int cx, int cy, int eff, double tlev, int spy)
@@ -208,7 +208,7 @@ rad_map_set(natid owner, int cx, int cy, int eff, double tlev, int spy)
 }
 
 /*
- * Range of a radar with EFF efficiency, TLEV tech, and SPY power.
+ * Range of a radar with @eff efficiency, @tlev tech, and @spy power.
  */
 static int
 rad_range(int eff, double tlev, int spy)
@@ -223,9 +223,9 @@ rad_range(int eff, double tlev, int spy)
 }
 
 /*
- * Return character to use in radar maps for sector SP.
+ * Return character to use in radar maps for sector @SP.
- * DIST is the distance from the radar, RANGE its range.
+ * @dist is the distance from the radar, @range its range.
- * Country CN is using the radar.
+ * Country @cn is using the radar.
  */
 static char
 rad_char(struct sctstr *sp, int dist, int range, natid cn)

src/lib/subs/show.c

@@ -605,7 +605,7 @@ show_updates(int n)
 }
 
 /*
- * Return T formatted according to RFC 2822.
+ * Return @t formatted according to RFC 2822.
  * The return value is statically allocated and overwritten on
  * subsequent calls.
  */

src/lib/subs/shpsub.c

@@ -145,7 +145,7 @@ shp_sel(struct nstr_item *ni, struct emp_qelem *list)
 }
 
 /*
- * Append SP to LIST.
+ * Append @sp to @list.
  * Return the new list link.
  */
 struct ulist *
@@ -224,11 +224,11 @@ shp_nav_put_one(struct ulist *mlp)
 }
 
 /*
- * Sweep seamines with engineers in SHIP_LIST for ACTOR.
+ * Sweep seamines with engineers in @ship_list for @actor.
- * All ships in SHIP_LIST must be in the same sector.
+ * All ships in @ship_list must be in the same sector.
- * If EXPLICIT is non-zero, this is for an explicit sweep command from
+ * If @explicit is non-zero, this is for an explicit sweep command from
  * a player.  Else it's an automatic "on the move" sweep.
- * If TAKEMOB is non-zero, require and charge mobility.
+ * If @takemob is non-zero, require and charge mobility.
  * Return non-zero when the ships should stop.
  */
 int
@@ -347,7 +347,7 @@ shp_check_mines(struct emp_qelem *ship_list)
 }
 
 /*
- * Return whether and why SP would be stuck in SECTP.
+ * Return whether and why @sp would be stuck in @sectp.
  */
 enum shp_stuck
 shp_check_nav(struct shpstr *sp, struct sctstr *sectp)
@@ -1005,7 +1005,7 @@ shp_mobcost(struct shpstr *sp)
 }
 
 /*
- * Set SP's tech to TLEV along with everything else that depends on it.
+ * Set @sp's tech to @tlev along with everything else that depends on it.
  */
 void
 shp_set_tech(struct shpstr *sp, int tlev)

src/lib/subs/snxtitem.c

@@ -218,8 +218,8 @@ snxtitem_list(struct nstr_item *np, int type, int *list, int len)
 }
 
 /*
- * Initialize NP to iterate over the items of type TYPE in a carrier.
+ * Initialize @np to iterate over the items of type @type in a carrier.
- * The carrier has file type CARRIER_TYPE and uid CARRIER_UID.
+ * The carrier has file type @carrier_type and uid @carrier_uid.
  * Note: you can take an item gotten with nxtitem() off its carrier
  * without disturbing the iterator.  Whether the iterator will pick up
  * stuff you load onto the carrier during iteration is unspecified.

src/lib/subs/trdsub.c

@@ -213,7 +213,7 @@ trade_getitem(struct trdstr *tp, union empobj_storage *tgp)
 }
 
 /*
- * Return amount due for LOAN at time PAYTIME.
+ * Return amount due for @loan at time @paytime.
  */
 double
 loan_owed(struct lonstr *loan, time_t paytime)

src/lib/subs/unitsub.c

@@ -464,8 +464,8 @@ unit_move(struct emp_qelem *list)
 }
 
 /*
- * Teleport UNIT to X,Y.
+ * Teleport @unit to @x,@y.
- * If UNIT's mission op-area is centered on it, keep it centered.
+ * If @unit's mission op-area is centered on it, keep it centered.
  */
 void
 unit_teleport(struct empobj *unit, coord x, coord y)
@@ -479,7 +479,7 @@ unit_teleport(struct empobj *unit, coord x, coord y)
 }
 
 /*
- * Update cargo of CARRIER for movement or destruction.
+ * Update cargo of @carrier for movement or destruction.
  * If the carrier is destroyed, destroy its cargo (planes, land units,
  * nukes).
  * Else update their location to the carrier's.  Any op sectors equal
@@ -511,8 +511,8 @@ unit_update_cargo(struct empobj *carrier)
 }
 
 /*
- * Drop cargo of UNIT.
+ * Drop cargo of @unit.
- * Give it to NEWOWN, unless it's zero.
+ * Give it to @newown, unless it's zero.
  */
 void
 unit_drop_cargo(struct empobj *unit, natid newown)
@@ -547,9 +547,9 @@ unit_drop_cargo(struct empobj *unit, natid newown)
 }
 
 /*
- * Give UNIT and its cargo to RECIPIENT.
+ * Give @unit and its cargo to @recipient.
- * No action if RECIPIENT already owns UNIT.
+ * No action if @recipient already owns @unit.
- * If GIVER is non-zero, inform RECIPIENT and GIVER of the transaction.
+ * If @giver is non-zero, inform @recipient and @giver of the transaction.
  * Clears mission and group on the units given away.
  */
 void
@@ -581,7 +581,7 @@ unit_give_away(struct empobj *unit, natid recipient, natid giver)
 }
 
 /*
- * Wipe orders and such from UNIT.
+ * Wipe orders and such from @unit.
  */
 void
 unit_wipe_orders(struct empobj *unit)

src/lib/subs/whatitem.c

@@ -36,7 +36,7 @@
 
 /*
  * Get item type argument.
- * If INPUT is not empty, use it, else prompt for more input using PROMPT.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
  * Return item characteristics on success, else NULL.
  */
 struct ichrstr *
@@ -56,7 +56,7 @@ whatitem(char *input, char *prompt)
 }
 
 /*
- * Map item type name STR to item characteristics, NULL if not found.
+ * Map item type name @str to item characteristics, NULL if not found.
  */
 struct ichrstr *
 item_by_name(char *str)

src/lib/subs/wu.c

@@ -73,11 +73,11 @@ telegram_is_new(natid to, struct telstr *tel)
 }
 
 /*
- * Send a telegram from FROM to TO.
+ * Send a telegram from @from to @to.
- * Format text to send using printf-style FORMAT and optional
+ * Format text to send using printf-style @format and optional
  * arguments.  It is plain ASCII.
  * If running from the update, telegram type is TEL_UPDATE.
- * Else if FROM is a deity, type is TEL_BULLETIN.
+ * Else if @from is a deity, type is TEL_BULLETIN.
  * Else it is TEL_NORM.
  * Return 0 on success, -1 on error.
  */
@@ -101,9 +101,9 @@ wu(natid from, natid to, char *format, ...)
 }
 
 /*
- * Send a telegram from FROM to TO.
+ * Send a telegram from @from to @to.
- * MESSAGE is the text to send, in UTF-8.
+ * @message is the text to send, in UTF-8.
- * TYPE is the telegram type.
+ * @type is the telegram type.
  * Return 0 on success, -1 on error.
  */
 int

src/lib/update/bp.c

@@ -74,8 +74,8 @@ bp_ref(struct bp *bp, struct sctstr *sp)
 }
 
 /*
- * Return the item value tracked in BP for sector SP's item COMM.
+ * Return the item value tracked in @bp for sector @sp's item @comm.
- * COMM must be a tracked item type.
+ * @comm must be a tracked item type.
  */
 int
 bp_get_item(struct bp *bp, struct sctstr *sp, i_type comm)
@@ -87,7 +87,7 @@ bp_get_item(struct bp *bp, struct sctstr *sp, i_type comm)
     return bp_ref(bp, sp)->bp_item[idx];
 }
 
-/* Set the item value tracked in BP for sector SP's item COMM.  */
+/* Set the item value tracked in @bp for sector @sp's item @comm. */
 void
 bp_put_item(struct bp *bp, struct sctstr *sp, i_type comm, int amount)
 {
@@ -97,7 +97,7 @@ bp_put_item(struct bp *bp, struct sctstr *sp, i_type comm, int amount)
 	bp_ref(bp, sp)->bp_item[idx] = amount;
 }
 
-/* Set the item values tracked in BP for sector SP from VEC.  */
+/* Set the item values tracked in @bp for sector @sp from @vec. */
 void
 bp_put_items(struct bp *bp, struct sctstr *sp, short *vec)
 {
@@ -112,21 +112,21 @@ bp_put_items(struct bp *bp, struct sctstr *sp, short *vec)
     }
 }
 
-/* Return avail tracked in BP for sector SP.  */
+/* Return avail tracked in @bp for sector @sp. */
 int
 bp_get_avail(struct bp *bp, struct sctstr *sp)
 {
     return bp_ref(bp, sp)->bp_avail;
 }
 
-/* Set avail tracked in BP for sector SP.  */
+/* Set avail tracked in @bp for sector @sp. */
 void
 bp_put_avail(struct bp *bp, struct sctstr *sp, int amount)
 {
     bp_ref(bp, sp)->bp_avail = amount;
 }
 
-/* Set the values tracked in BP for sector SP to the values in SP.  */
+/* Set the values tracked in @bp for sector @sp to the values in @sp. */
 void
 bp_set_from_sect(struct bp *bp, struct sctstr *sp)
 {

src/lib/update/human.c

@@ -171,7 +171,7 @@ feed_people(short *vec, int etu)
 }
 
 /*
- * Return food eaten by people in VEC[] in ETU ETUs.
+ * Return food eaten by people in @vec[] in @etu ETUs.
  */
 double
 food_needed(short *vec, int etu)
@@ -182,7 +182,7 @@ food_needed(short *vec, int etu)
 }
 
 /*
- * Return number of famine victims in VEC[] for ETU ETUs.
+ * Return number of famine victims in @vec[] for @etu ETUs.
  */
 int
 famine_victims(short *vec, int etu)
@@ -197,7 +197,7 @@ famine_victims(short *vec, int etu)
 }
 
 /*
- * Starve up to NUM people of VEC[WHOM].
+ * Starve up to @num people of @vec[@whom].
  * Return the number of actually starved.
  */
 static int
@@ -252,10 +252,10 @@ grow_people(struct sctstr *sp, int etu,
 }
 
 /*
- * Return the number of babies born to ADULTS in ETU ETUs.
+ * Return the number of babies born to @adults in @etu ETUs.
- * BRATE is the birth rate.
+ * @brate is the birth rate.
- * FOOD is the food available for growing babies.
+ * @food is the food available for growing babies.
- * MAXPOP is the population limit.
+ * @maxpop is the population limit.
  */
 static int
 babies(int adults, int etu, double brate, int food, int maxpop)

src/lib/update/material.c

@@ -39,10 +39,10 @@
 #include "update.h"
 
 /*
- * Get build materials from sector SP.
+ * Get build materials from sector @sp.
- * BP is the sector's build pointer.
+ * @bp is the sector's build pointer.
- * MVEC[] defines the materials needed to build 100%.
+ * @mvec[] defines the materials needed to build 100%.
- * PCT is the percentage to build.
+ * @pct is the percentage to build.
  * Adjust build percentage downwards so that available materials
  * suffice.  Remove the materials.
  * Return adjusted build percentage.

src/lib/update/produce.c

@@ -170,8 +170,8 @@ produce(struct natstr *np, struct sctstr *sp, short *vec, int work,
 }
 
 /*
- * Return how much of product PP can be made from materials VEC[].
+ * Return how much of product @pp can be made from materials @vec[].
- * Store amount of work per unit in *COSTP.
+ * Store amount of work per unit in *@costp.
  */
 int
 prod_materials_cost(struct pchrstr *pp, short vec[], int *costp)
@@ -216,8 +216,8 @@ materials_charge(struct pchrstr *pp, short *vec, int count)
 }
 
 /*
- * Return how much of product PP can be made from its resource.
+ * Return how much of product @pp can be made from its resource.
- * If PP depletes a resource, RESOURCE must point to its value.
+ * If @pp depletes a resource, @resource must point to its value.
  */
 int
 prod_resource_limit(struct pchrstr *pp, unsigned char *resource)
@@ -230,9 +230,9 @@ prod_resource_limit(struct pchrstr *pp, unsigned char *resource)
 }
 
 /*
- * Return p.e. for sector type TYPE.
+ * Return p.e. for sector type @type.
  * Zero means level is too low for production.
- * LEVEL is the affecting production of PP; it must match PP->p_nlndx.
+ * @level is the affecting production of PP; it must match PP->p_nlndx.
  */
 double
 prod_eff(int type, float level)

src/lib/update/sect.c

@@ -181,8 +181,8 @@ meltitems(int etus, int fallout, int own, short *vec,
 }
 
 /*
- * Do fallout meltdown for sector SP.
+ * Do fallout meltdown for sector @sp.
- * ETUS above 24 are treated as 24 to avoid *huge* kill offs in
+ * @etus above 24 are treated as 24 to avoid *huge* kill offs in
  * large ETU games.
  */
 void

src/server/shutdown.c

@@ -44,8 +44,8 @@ static empth_t *shutdown_thread;
 static void shutdown_sequence(void *unused);
 
 /*
- * Initiate shutdown in MINS_FROM_NOW minutes.
+ * Initiate shutdown in @mins_from_now minutes.
- * If MINS_FROM_NOW is negative, cancel any pending shutdown instead.
+ * If @mins_from_now is negative, cancel any pending shutdown instead.
  * Return -1 on error, zero when no shutdown was pending, positive
  * number when a pending shutdown was modified.
  */