diff --git a/include/empthread.h b/include/empthread.h
index 5a347a35..b1538ff5 100644
--- a/include/empthread.h
+++ b/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().
- * FLAGS request optional features.
+ * @ctx points to a thread context variable; see empth_create().
+ * @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.
- * 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.
- * UD is the value to pass to ENTRY.  It is also assigned to the
+ * Thread stack is at least @size bytes.
+ * @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.
+ * @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.
- * 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.
+ * 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_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.
- * Return one when the FD is ready, zero on timeout or early wakeup by
+ * @timeout, if non-null, limits the sleep time.
+ * 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.
- * The current thread must hold RWLOCK.
+ * Unlock read-write lock @rwlock.
+ * The current thread must hold @rwlock.
  * Wake up threads that can now lock it.
  */
 void empth_rwlock_unlock(empth_rwlock_t *rwlock);
diff --git a/include/map.h b/include/map.h
index a84ef368..ef33335d 100644
--- a/include/map.h
+++ b/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
- * characters.  For even PERSEC, it's either PERSEC/2 or PERSEC/2 + 1,
+ * adjacent rows.  For odd @persec, that's (@persec+1)/2 additional
+ * 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).
  *
diff --git a/include/misc.h b/include/misc.h
index 29833292..cce94dfc 100644
--- a/include/misc.h
+++ b/include/misc.h
@@ -60,8 +60,8 @@
 #define days(x)		(60*60*24*(x))
 
 /*
- * If EXPR is true, an internal error occured.
- * Return EXPR != 0.
+ * If @expr is true, an internal error occured.
+ * Return @expr != 0.
  * Usage: if (CANT_HAPPEN(...)) <recovery code>;
  */
 #define CANT_HAPPEN(expr) ((expr) ? oops(#expr, __FILE__, __LINE__), 1 : 0)
diff --git a/include/nsc.h b/include/nsc.h
index 553e6b56..7596707c 100644
--- a/include/nsc.h
+++ b/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.
- * If ca_get is null, the selector describes a datum of type ca_type
- * at offset ca_offs in the context object.
+ * A selector with @ca_type NSC_NOTYPE is invalid.
+ * If @ca_get is null, the selector describes a datum of type @ca_type
+ * 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.
- * 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
+ * @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
+ * 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;
- * ca_type must be an integer type.  If flag NSC_BITS is set, the
+ * 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
  * datum consists of flag bits, and the referred table must be a
  * symbol table defining those bits.
  */
diff --git a/src/client/linebuf.c b/src/client/linebuf.c
index dd006942..e00a310f 100644
--- a/src/client/linebuf.c
+++ b/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.
- * LBUF must not be full.
- * If CH is a newline, the buffer is now full.  Return the line
+ * Append @ch to the line buffered in @lbuf.
+ * @lbuf must not be full.
+ * 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.
  */
diff --git a/src/client/play.c b/src/client/play.c
index f7255420..47e028a8 100644
--- a/src/client/play.c
+++ b/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.
  */
diff --git a/src/client/ringbuf.c b/src/client/ringbuf.c
index fdb49fa3..141f8982 100644
--- a/src/client/ringbuf.c
+++ b/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.
- * 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.
+ * @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-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.
- * Return EOF when the buffer is full, else C.
+ * Attempt to put byte @c into the ring buffer.
+ * 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.
diff --git a/src/client/secure.c b/src/client/secure.c
index 3d73c633..9760b16c 100644
--- a/src/client/secure.c
+++ b/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.
- * SEEN should be obtained from save_input() or seen_input().
+ * Forget remembered input up to @seen.
+ * @seen should be obtained from save_input() or seen_input().
  */
 void
 forget_input(size_t seen)
diff --git a/src/lib/commands/flash.c b/src/lib/commands/flash.c
index a74226f3..13c22355 100644
--- a/src/lib/commands/flash.c
+++ b/src/lib/commands/flash.c
@@ -79,9 +79,9 @@ wall(void)
 }
 
 /*
- * Send flash message(s) from US to TO.
- * Null TO broadcasts to all.
- * MESSAGE is UTF-8.  If it is null, prompt for messages interactively.
+ * Send flash message(s) from @us to @to.
+ * Null @to broadcasts to all.
+ * @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.
- * MESSAGE is UTF-8.
- * Null TO broadcasts to all.
- * A header identifying US is prepended to the message.  It is more
- * verbose if VERBOSE.
+ * Send flash message @message from @us to @to.
+ * @message is UTF-8.
+ * Null @to broadcasts to all.
+ * A header identifying @us is prepended to the message.  It is more
+ * verbose if @verbose.
  */
 static int
 sendmessage(struct natstr *to, char *message, int verbose)
diff --git a/src/lib/commands/laun.c b/src/lib/commands/laun.c
index 04900bac..0d08f592 100644
--- a/src/lib/commands/laun.c
+++ b/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.
  */
diff --git a/src/lib/commands/rea.c b/src/lib/commands/rea.c
index 07f2fc81..24989d01 100644
--- a/src/lib/commands/rea.c
+++ b/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)
diff --git a/src/lib/commands/xdump.c b/src/lib/commands/xdump.c
index 32e1d5b0..b8a730cb 100644
--- a/src/lib/commands/xdump.c
+++ b/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.
- * Return RET_SYN when TYPE doesn't have meta-data, else RET_OK.
+ * Dump meta-data for items of type @type to @xd.
+ * 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
diff --git a/src/lib/common/btu.c b/src/lib/common/btu.c
index 0e7569d6..6ac62dce 100644
--- a/src/lib/common/btu.c
+++ b/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
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ *  but @WITHOUT @ANY @WARRANTY; without even the implied warranty of
+ *  @MERCHANTABILITY or @FITNESS @FOR A @PARTICULAR @PURPOSE.  See the
+ *  @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
diff --git a/src/lib/common/cargo.c b/src/lib/common/cargo.c
index 5c36377d..18a5fe58 100644
--- a/src/lib/common/cargo.c
+++ b/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.
- * UID must not be on any cargo list already.
+ * Add to @cl's cargo list for type @type the uid @uid.
+ * @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.
- * UID must be on that cargo list.
+ * Remove from @cl's cargo list for type @type the uid @uid.
+ * @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.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @cargo's carrier.
+ * 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.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @pp's carrier.
+ * 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.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @lp's carrier.
+ * 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.
- * Carrier is of type TYPE, and changes from uid OLD to NEW.
+ * Update cargo lists for a change of @np's carrier.
+ * 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.
- * Search carrier UID of type TYPE.
+ * Find first unit on a carrier's cargo list for file type @cargo_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.
- * Get the unit after CARGO_UID.
+ * Find the next unit on a cargo list for file type @cargo_type.
+ * 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)
diff --git a/src/lib/common/cnumb.c b/src/lib/common/cnumb.c
index 363f17a0..fc2baddd 100644
--- a/src/lib/common/cnumb.c
+++ b/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.
  */
diff --git a/src/lib/common/conftab.c b/src/lib/common/conftab.c
index 2f6b5d35..9a743d28 100644
--- a/src/lib/common/conftab.c
+++ b/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
diff --git a/src/lib/common/ef_verify.c b/src/lib/common/ef_verify.c
index ae64aa5f..f1159d67 100644
--- a/src/lib/common/ef_verify.c
+++ b/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
diff --git a/src/lib/common/file.c b/src/lib/common/file.c
index 0d398222..090e943a 100644
--- a/src/lib/common/file.c
+++ b/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, ...).
- * HOW are flags to control operation.  Naturally, immutable flags are
+ * Open the file-backed table @type (EF_SECTOR, ...).
+ * @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.
- * ID is its new element ID.
- * If table is EFF_TYPED, change id and sequence number stored in BUF.
+ * @buf is an element of table @type.
+ * @id is its new element ID.
+ * 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.
- * If necessary, extend it in steps of COUNT elements.
+ * Ensure table contains element @id.
+ * 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
diff --git a/src/lib/common/game.c b/src/lib/common/game.c
index 9729b373..a1598bd2 100644
--- a/src/lib/common/game.c
+++ b/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
diff --git a/src/lib/common/hours.c b/src/lib/common/hours.c
index ac35bf6e..2ed3febe 100644
--- a/src/lib/common/hours.c
+++ b/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?
- * If DAYS is not empty, it lists the allowed week day names.  See
+ * Is week day @wday (Sunday is 0) allowed by restriction @days?
+ * 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?
- * If TIMES is not empty, it lists the allowed day time ranges.  See
+ * Is day time @dtime (minutes since midnight) allowed by restriction @times?
+ * 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.
- * On success assign day number (Sunday is 0) to *WDAY and return
+ * Parse weekday name in @str.
+ * 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.
- * On success store minutes since midnight in *MIN and return pointer
+ * Parse day time in @str.
+ * 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.
- * On success store minutes since midnight in *FROM and *TO, return
+ * Parse a day time range in @str.
+ * 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.
diff --git a/src/lib/common/mailbox.c b/src/lib/common/mailbox.c
index 90a8847f..963acf31 100644
--- a/src/lib/common/mailbox.c
+++ b/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.
- * MBOX is the file name, it is used for logging errors.
+ * Read telegram header from @fp into @tel.
+ * @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.
- * MBOX is the file name, it is used for logging errors.
- * TEL is the header.
- * Unless SINK is null, it is called like SINK(CHUNK, SZ, ARG) to
+ * Read telegram body from @fp.
+ * @mbox is the file name, it is used for logging errors.
+ * @tel is the header.
+ * 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.
  */
diff --git a/src/lib/common/nat.c b/src/lib/common/nat.c
index 36f5c2d0..5851aa94 100644
--- a/src/lib/common/nat.c
+++ b/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.
- * STAT must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
+ * Initialize @natp for country #@cnum in status @stat.
+ * @stat must be STAT_UNUSED, STAT_NEW, STAT_VIS or STAT_GOD.
  * Also wipe realms and telegrams.
  */
 struct natstr *
diff --git a/src/lib/common/nstreval.c b/src/lib/common/nstreval.c
index f7cdbec3..fa9d7b71 100644
--- a/src/lib/common/nstreval.c
+++ b/src/lib/common/nstreval.c
@@ -43,8 +43,8 @@
 #include "optlist.h"
 
 /*
- * Initialize VAL to symbolic value for selector CA with index IDX.
- * Return VAL.
+ * Initialize @val to symbolic value for selector @ca with index @idx.
+ * 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.
- * If VAL has category NSC_OFF, read the value from the context object
- * PTR, and translate it for country CNUM (coordinate system and
- * contact status).  No translation when CNUM is NATID_BAD.
- * PTR points to a context object of the type that was used to compile
+ * Evaluate @val.
+ * If @val has category NSC_OFF, read the value from the context object
+ * @ptr, and translate it for country @cnum (coordinate system and
+ * contact status).  No translation when @cnum is NATID_BAD.
+ * @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
- * WANT.  VAL must be coercible.
+ * Unless @want is NSC_NOTYPE, coerce the value to promoted value type
+ * @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.
- * If VALTYPE is an integer type, return NSC_LONG.
- * If VALTYPE is a floating-point type, return NSC_DOUBLE.
- * If VALTYPE is a string type, return NSC_STRING.
+ * Promote @valtype.
+ * If @valtype is an integer type, return NSC_LONG.
+ * If @valtype is a floating-point type, return NSC_DOUBLE.
+ * If @valtype is a string type, return NSC_STRING.
  */
 int
 nstr_promote(int valtype)
diff --git a/src/lib/common/pathfind.c b/src/lib/common/pathfind.c
index 2856952c..1a8f0870 100644
--- a/src/lib/common/pathfind.c
+++ b/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.
- * UID is sector uid, it equals XYOFFSET(X,Y).
- * Cheapest path from source comes from direction DIR and has cost COST.
+ * Open the unvisited sector @x,@y.
+ * @uid is sector uid, it equals XYOFFSET(@x,@y).
+ * 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.
- * The cost to enter the sector with uid u is COST(ACTOR, u).
+ * @sx,@sy is the source.
+ * 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.
- * If the route is longer than BUFSIZ-1 characters, it's truncated.
+ * 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.
  * 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.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Start finding paths from @sx,@sy.
+ * 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.
- * Use mobility costs for ACTOR and MOBTYPE.
+ * Find cheapest path from @sx,@sy to @dx,@dy, return its mobility cost.
+ * Use mobility costs for @actor and @mobtype.
  */
 double
 path_find(coord sx, coord sy, coord dx, coord dy, natid actor, int mobtype)
diff --git a/src/lib/common/rdsched.c b/src/lib/common/rdsched.c
index 1ef1d579..57960016 100644
--- a/src/lib/common/rdsched.c
+++ b/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.
- * Put the first N-1 updates after T0 into SCHED[] in ascending order,
+ * Read update schedule from file @fname.
+ * 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.
- * Update SCHED[] and ANCHOR accordingly.
- * SCHED[] holds the first N-1 updates after T0 in ascending order.
- * FNAME and LNO file name and line number for reporting errors.
+ * Parse an update schedule directive from @line.
+ * Update @sched[] and @anchor accordingly.
+ * @sched[] holds the first N-1 updates after @t0 in ascending order.
+ * @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.
- * FNAME and LNO file name and line number.
+ * Complain and return zero when @t is bad, else return non-zero.
+ * @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.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse a time from @s into *@t.
+ * *@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.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse an until clause from @s into *@t.
+ * *@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.
- * *ANCHOR is the base for anchor-relative time.
+ * Parse an skip clause from @s into *@t.
+ * *@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[].
- * 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 there's no space for T in SCHED[], return N-1.
- * Else insert T into SCHED[] and return its index in SCHED[].
+ * Insert update at @t into @sched[].
+ * @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 there's no space for @t in @sched[], return N-1.
+ * 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[].
- * SCHED[] holds N-1 updates in ascending order.
- * Return the index of the first update after T in SCHED[].
+ * Delete update @t from @sched[].
+ * @sched[] holds @n-1 updates in ascending order.
+ * Return the index of the first update after @t in @sched[].
  */
 static int
 delete_update(time_t t, time_t sched[], int n)
diff --git a/src/lib/common/stmtch.c b/src/lib/common/stmtch.c
index 6965a20d..d55550c0 100644
--- a/src/lib/common/stmtch.c
+++ b/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).
- * SIZE gives the size of an array element.
+ * @needle is compared to element names with mineq(@needle, NAME).
+ * @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.
- * Return ME_EXACT if they are the same, or A is a prefix of B
- * followed by a space in B.
- * Return ME_PARTIAL if A is a prefix of B not followed by a space.
+ * Compare @a with @b.
+ * Return ME_EXACT if they are the same, or @a is a prefix of @b
+ * followed by a space in @b.
+ * Return ME_PARTIAL if @a is a prefix of @b not followed by a space.
  * Else return ME_MISMATCH.
  */
 int
diff --git a/src/lib/common/type.c b/src/lib/common/type.c
index 6f87ca69..e7d0c998 100644
--- a/src/lib/common/type.c
+++ b/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.
diff --git a/src/lib/common/xdump.c b/src/lib/common/xdump.c
index 590ea949..49fbb92d 100644
--- a/src/lib/common/xdump.c
+++ b/src/lib/common/xdump.c
@@ -80,13 +80,13 @@
 #include "xdump.h"
 
 /*
- * Initialize XD.
- * Translate dump for country CNUM, except when CNUM is NATID_BAD.
- * If HUMAN, dump in human-readable format.
- * If SLOPPY, try to cope with invalid data (may result in invalid
+ * Initialize @xd.
+ * Translate dump for country @cnum, except when @cnum is NATID_BAD.
+ * If @human, dump in human-readable format.
+ * If @sloppy, try to cope with invalid data (may result in invalid
  * dump).
- * Dump is to be delivered through callback PR.
- * Return XD.
+ * Dump is to be delivered through callback @pr.
+ * 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.
- * CA describes the attribute.
- * XD is the xdump descriptor.
- * PTR points to the context object.
- * IDX is the index within the attribute.
+ * Evaluate a attribute of an object into @val, return @val.
+ * @ca describes the attribute.
+ * @xd is the xdump descriptor.
+ * @ptr points to the context object.
+ * @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 at most N characters.
+ * Dump string @str to @xd with funny characters escaped.
+ * 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.
- * VAL must be evaluated.
+ * Dump @val prefixed with @sep to @xd, in machine readable format.
+ * @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.
- * Prefix with SEP, return " ".
+ * Dump symbol with value @key from symbol table @type to @xd.
+ * 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 " ".
- * VAL must be evaluated.
- * CA describes the field from which the value was fetched.
+ * Dump @val prefixed with @sep to @xd, return " ".
+ * @val must be evaluated.
+ * @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.
- * CA[] describes fields.
- * PTR points to context object.
+ * Dump field values of a context object to @xd.
+ * @ca[] describes fields.
+ * @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.
- * If META, it's for the meta-data dump rather than the data dump.
+ * Dump header for dump @name to @xd.
+ * 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.
- * CA[] describes fields.
- * Does nothing unless XD is human-readable.
+ * Dump column header to @xd.
+ * @ca[] describes fields.
+ * Does nothing unless @xd is human-readable.
  */
 void
 xdcolhdr(struct xdstr *xd, struct castr ca[])
diff --git a/src/lib/common/xundump.c b/src/lib/common/xundump.c
index 27770173..ff551d98 100644
--- a/src/lib/common/xundump.c
+++ b/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.
- * Assign the field's selector index to *IDX, unless it is null.
+ * Get selector for field @fldno.
+ * 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.
- * Return BUF on success, null pointer on failure.
+ * Decode escape sequences in @buf.
+ * 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.
- * BUF must have space for 1024 characters.
+ * Read an identifier from @fp into @buf.
+ * @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.
- * I is the field number, counting from zero.
- * If a name is read, set fldca[I] and fldidx[I] for it, and update
+ * Try to read a field name from @fp.
+ * @i is the field number, counting from zero.
+ * 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.
- * I is the field number, counting from zero.
+ * Try to read a field value from @fp.
+ * @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.
- * Use PARSE() to read each field.
+ * Read fields from @fp.
+ * 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.
- * If IDX is negative, define as selector NAME, else as NAME(IDX).
- * Set fldca[FLDNO] and fldidx[FLDNO] accordingly.
+ * Define the @fldno-th field.
+ * If @idx is negative, define as selector @name, else as @name(@idx).
+ * 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.
- * Use field number N for error messages.
+ * Resolve symbol name @id in table referred to by @ca.
+ * 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.
- * SYM is the name of the symbol to add.
+ * Add a symbol to a symbol set for field @fldno in *@set.
+ * @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.
- * Expect header for EXPECTED_TABLE, unless it is EF_BAD.
+ * Read an xdump table header line from @fp.
+ * 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.
- * Else take fields from the table's selectors in CA[].
+ * If reading human-readable syntax, read a field header line from @fp.
+ * 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.
- * CA[] contains the table's selectors.
- * The body had RECS records.
+ * Read xdump footer from @fp.
+ * @ca[] contains the table's selectors.
+ * 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.
- * Update *PLNO to reflect lines read from FP.
+ * Messages assume @fp starts in the file @file at line *@plno.
+ * 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.
- * CA[] contains the table's selectors.
+ * Read the remainder of an xdump after the table header line from @fp.
+ * @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
diff --git a/src/lib/common/xy.c b/src/lib/common/xy.c
index 2a47ddda..3b0bd55b 100644
--- a/src/lib/common/xy.c
+++ b/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,
- * unless END is a null pointer.
+ * Assign pointer to first character after the coordinate to *@end,
+ * 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,
- * unless END is a null pointer.
+ * Assign pointer to first character after the coordinate to *@end,
+ * unless @end is a null pointer.
  */
 coord
 strtoy(char *str, char **end)
diff --git a/src/lib/empthread/io.c b/src/lib/empthread/io.c
index 075277ef..c3333da7 100644
--- a/src/lib/empthread/io.c
+++ b/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.
- * Wait at most until DEADLINE for input to arrive.  (time_t)-1 means
+ * Read input from @iop and enqueue it.
+ * 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.
- * Wait at most until DEADLINE for input to arrive.  (time_t)-1 means
+ * Write output queued in @iop.
+ * 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.
- * No more input can be read from IOP.
+ * Discard @iop's buffered input and set its EOF flag.
+ * No more input can be read from @iop.
  */
 void
 io_set_eof(struct iop *iop)
diff --git a/src/lib/gen/chance.c b/src/lib/gen/chance.c
index b20dfb9b..703bcff3 100644
--- a/src/lib/gen/chance.c
+++ b/src/lib/gen/chance.c
@@ -50,7 +50,7 @@ chance(double d)
 }
 
 /*
- * Return non-zero with probability PCT%.
+ * Return non-zero with probability @pct%.
  */
 int
 pct_chance(int pct)
@@ -98,8 +98,8 @@ roll(int n)
 }
 
 /*
- * Round VAL to nearest integer (on the average).
- * VAL's fractional part is chance to round up.
+ * Round @val to nearest integer (on the average).
+ * @val's fractional part is chance to round up.
  */
 int
 roundavg(double val)
@@ -109,7 +109,7 @@ roundavg(double val)
 }
 
 /*
- * Seed the pseudo-random number generator with SEED.
+ * Seed the pseudo-random number generator with @seed.
  * The sequence of pseudo-random numbers is repeatable by seeding it
  * with the same value.
  */
diff --git a/src/lib/gen/fnameat.c b/src/lib/gen/fnameat.c
index 6452f2c3..181b74ab 100644
--- a/src/lib/gen/fnameat.c
+++ b/src/lib/gen/fnameat.c
@@ -38,9 +38,9 @@
 static int fname_is_abs(const char *);
 
 /*
- * Interpret FNAME relative to directory DIR.
- * Return FNAME if it is absolute, or DIR is null or empty.
- * Else return a malloc'ed string containing DIR/FNAME, or null
+ * Interpret @fname relative to directory @dir.
+ * Return @fname if it is absolute, or @dir is null or empty.
+ * Else return a malloc'ed string containing @dir/@fname, or null
  * pointer when that fails.
  */
 char *
@@ -73,8 +73,8 @@ fname_is_abs(const char *fname)
 
 /*
  * Open a stream like fopen(), optionally relative to a directory.
- * This is exactly like fopen(), except FNAME is interpreted relative
- * to DIR if that is neither null nor empty.
+ * This is exactly like fopen(), except @fname is interpreted relative
+ * to @dir if that is neither null nor empty.
  */
 FILE *
 fopenat(const char *fname, const char *mode, const char *dir)
diff --git a/src/lib/gen/fsize.c b/src/lib/gen/fsize.c
index 5ecbad85..6b663d02 100644
--- a/src/lib/gen/fsize.c
+++ b/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)
diff --git a/src/lib/gen/log.c b/src/lib/gen/log.c
index e0bbfa3f..30a7f222 100644
--- a/src/lib/gen/log.c
+++ b/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)
diff --git a/src/lib/gen/parse.c b/src/lib/gen/parse.c
index 42d16562..2c156aef 100644
--- a/src/lib/gen/parse.c
+++ b/src/lib/gen/parse.c
@@ -36,19 +36,19 @@
 #include "prototypes.h"
 
 /*
- * Parse user command in BUF.
- * BUF is UTF-8.
- * Command name and arguments are copied into SPACE[], whose size must
- * be at least strlen(BUF) + 1.
- * Set ARG[0] to the zero-terminated command name.
- * Set ARG[1..N] to the zero-terminated arguments, where N is the
- * number of arguments.  Set ARG[N+1..127] to NULL.
- * Set TAIL[0..N] to beginning of ARG[0] in BUF[].
- * If CONDP is not null, recognize conditional argument syntax, and
- * set *CONDP to the conditional argument if present, else NULL.
- * If REDIR is not null, recognize redirection syntax, and set *REDIR
+ * Parse user command in @buf.
+ * @buf is UTF-8.
+ * Command name and arguments are copied into @space[], whose size must
+ * be at least strlen(@buf) + 1.
+ * Set @arg[0] to the zero-terminated command name.
+ * Set @arg[1..N] to the zero-terminated arguments, where N is the
+ * number of arguments.  Set @arg[N+1..127] to NULL.
+ * Set @tail[0..N] to beginning of @arg[0] in @buf[].
+ * If @condp is not null, recognize conditional argument syntax, and
+ * set *@condp to the conditional argument if present, else NULL.
+ * If @redir is not null, recognize redirection syntax, and set *@redir
  * to UTF-8 redirection string if present, else NULL.
- * Return number of slots used in ARG[], or -1 on error.
+ * Return number of slots used in @arg[], or -1 on error.
  */
 int
 parse(char *buf, char *space, char **arg,
diff --git a/src/lib/lwp/sel.c b/src/lib/lwp/sel.c
index 57a68303..ddaa74f0 100644
--- a/src/lib/lwp/sel.c
+++ b/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
diff --git a/src/lib/lwp/sig.c b/src/lib/lwp/sig.c
index 01ded424..031066ec 100644
--- a/src/lib/lwp/sig.c
+++ b/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.
- * Assign its number to *SIG and return 0.
+ * Wait until a signal from @set arrives.
+ * Assign its number to *@sig and return 0.
  * If another thread is already waiting for signals, return EBUSY
  * without waiting.
  */
diff --git a/src/lib/player/accept.c b/src/lib/player/accept.c
index 8aa922c4..48c6fe01 100644
--- a/src/lib/player/accept.c
+++ b/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)
diff --git a/src/lib/player/dispatch.c b/src/lib/player/dispatch.c
index 02a888a4..5d8f10df 100644
--- a/src/lib/player/dispatch.c
+++ b/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
diff --git a/src/lib/player/empdis.c b/src/lib/player/empdis.c
index dcdd6c76..9cdecb11 100644
--- a/src/lib/player/empdis.c
+++ b/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.
diff --git a/src/lib/player/player.c b/src/lib/player/player.c
index a8e9ab62..2747ee86 100644
--- a/src/lib/player/player.c
+++ b/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()
diff --git a/src/lib/player/recvclient.c b/src/lib/player/recvclient.c
index 93333d2e..2088ec2c 100644
--- a/src/lib/player/recvclient.c
+++ b/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,
diff --git a/src/lib/subs/actofgod.c b/src/lib/subs/actofgod.c
index 24c5638f..506e2ae6 100644
--- a/src/lib/subs/actofgod.c
+++ b/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.
- * If CHANGE is zero, the meddling is a no-op (bulletin suppressed).
- * If CHANGE is negative, it's secret (bulletin suppressed).
- * If a bulletin is sent, report N_AIDS news for positive GOODNESS,
- * N_HURTS news for negative GOODNESS
- * The bulletin's text is like "NAME of sector X,Y changed <how> by an
+ * @name names what is being changed in the sector.
+ * If @change is zero, the meddling is a no-op (bulletin suppressed).
+ * If @change is negative, it's secret (bulletin suppressed).
+ * If a bulletin is sent, report N_AIDS news for positive @goodness,
+ * N_HURTS news for negative @goodness
+ * 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.
- * Give AMT of IP in PLACE.
+ * Report deity giving/taking commodities to/from @whom.
+ * Give @amt of @ip in @place.
  */
 void
 report_divine_gift(natid whom, struct ichrstr *ip, int amt, char *place)
diff --git a/src/lib/subs/attsub.c b/src/lib/subs/attsub.c
index 7ff65fd5..d7a9a193 100644
--- a/src/lib/subs/attsub.c
+++ b/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.
- * MOBTYPE is a mobility type accepted by sector_mcost().
+ * Return path cost for @attacker to enter sector given by @def.
+ * @mobtype is a mobility type accepted by sector_mcost().
  */
 static double
 att_mobcost(natid attacker, struct combat *def, int mobtype)
diff --git a/src/lib/subs/bridgefall.c b/src/lib/subs/bridgefall.c
index 426bba70..bdb9bd33 100644
--- a/src/lib/subs/bridgefall.c
+++ b/src/lib/subs/bridgefall.c
@@ -49,8 +49,8 @@
 static void knockdown(struct sctstr *);
 
 /*
- * Is there support for a bridge at SP?
- * Ignore support coming from direction IGNORE_DIR.
+ * Is there support for a bridge at @sp?
+ * 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.
- * If SP is an inefficent bridge, splash it.
- * If SP can't support a bridge, splash unsupported adjacent bridges.
- * Write back splashed bridges, except for SP; writing that one is
+ * Check bridges at and around @sp after damage to @sp.
+ * If @sp is an inefficent bridge, splash it.
+ * If @sp can't support a bridge, splash unsupported adjacent bridges.
+ * Write back splashed bridges, except for @sp; writing that one is
  * left to the caller.
  */
 void
diff --git a/src/lib/subs/coastal.c b/src/lib/subs/coastal.c
index 63c3d538..741939b7 100644
--- a/src/lib/subs/coastal.c
+++ b/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.
- * Update adjacent sectors, but don't touch SP.
+ * Compute coastal flags for a change of @sp from @olddes to @newdes.
+ * Update adjacent sectors, but don't touch @sp.
  */
 void
 set_coastal(struct sctstr *sp, int olddes, int newdes)
diff --git a/src/lib/subs/control.c b/src/lib/subs/control.c
index 4c55b6c1..23f9f63f 100644
--- a/src/lib/subs/control.c
+++ b/src/lib/subs/control.c
@@ -65,10 +65,10 @@ military_control(struct sctstr *sp)
 }
 
 /*
- * Ask user to confirm abandonment of sector SP, if any.
- * If removing AMNT commodities of type VTYPE and the land units in
- * LIST would abandon their sector, ask the user to confirm.
- * All land units in LIST must be in this sector.  LIST may be null.
+ * Ask user to confirm abandonment of sector @sp, if any.
+ * If removing @amnt commodities of type @vtype and the land units in
+ * @list would abandon their sector, ask the user to confirm.
+ * 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?
- * Consider removal of AMNT commodities of type VTYPE and the land
- * units in LIST.
- * All land units in LIST must be in this sector.  LIST may be null.
+ * Would removing this stuff from @sp abandon it?
+ * Consider removal of @amnt commodities of type @vtype and the land
+ * units in @list.
+ * 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,
diff --git a/src/lib/subs/fortdef.c b/src/lib/subs/fortdef.c
index eea71ce4..b968b001 100644
--- a/src/lib/subs/fortdef.c
+++ b/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)
diff --git a/src/lib/subs/getele.c b/src/lib/subs/getele.c
index f414d973..8dce3513 100644
--- a/src/lib/subs/getele.c
+++ b/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.
- * BUF must have space for MAXTELSIZE+1 characters.
+ * Read a telegram for @recipient into @buf, in UTF-8.
+ * @buf must have space for MAXTELSIZE+1 characters.
  * Return telegram length, or -1 on error.
  */
 int
diff --git a/src/lib/subs/getstarg.c b/src/lib/subs/getstarg.c
index 6446611a..de158f07 100644
--- a/src/lib/subs/getstarg.c
+++ b/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.
- * Copy input to BUF[1024].
- * Return BUF on success, else NULL.
+ * If @input is not empty, use it, else prompt for more input using @prompt.
+ * Copy input to @buf[1024].
+ * Return @buf on success, else NULL.
  */
 char *
 getstarg(char *input, char *prompt, char *buf)
diff --git a/src/lib/subs/getstring.c b/src/lib/subs/getstring.c
index 5a0dd211..ac59529c 100644
--- a/src/lib/subs/getstring.c
+++ b/src/lib/subs/getstring.c
@@ -35,8 +35,8 @@
 #include "prototypes.h"
 
 /*
- * Print sub-prompt PROMPT, receive a line of input into BUF[1024].
- * Return BUF on success, else NULL.
+ * Print sub-prompt @prompt, receive a line of input into @buf[1024].
+ * 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].
- * Return BUF on success, else NULL.
+ * Print sub-prompt @prompt, receive a line of UTF-8 input into @buf[1024].
+ * Return @buf on success, else NULL.
  */
 char *
 ugetstring(char *prompt, char *buf)
diff --git a/src/lib/subs/landgun.c b/src/lib/subs/landgun.c
index f421c665..5e84fc9c 100644
--- a/src/lib/subs/landgun.c
+++ b/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)
diff --git a/src/lib/subs/lndsub.c b/src/lib/subs/lndsub.c
index 6a52b238..79b7464a 100644
--- a/src/lib/subs/lndsub.c
+++ b/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.
- * 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
+ * Sweep landmines with engineers in @land_list for @actor.
+ * 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
  * 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.
- * If removing the land units in LIST would abandon their sector, ask
+ * All land units in @list must be in the same sector.
+ * 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.
- * If DEFENDING, this is defensive support, else offensive support.
+ * Fire land unit support against @victim for @attacker, at @x,@y.
+ * 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.
- * Fortification costs mobility.  Use up to MOB mobility.
+ * Increase fortification value of @lp.
+ * 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)
diff --git a/src/lib/subs/lostsub.c b/src/lib/subs/lostsub.c
index c5546b4f..7c2f4957 100644
--- a/src/lib/subs/lostsub.c
+++ b/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.
- * Else if FREE is non-zero, return the index of an unused record.
+ * 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 return -1.
  */
 static int
diff --git a/src/lib/subs/maps.c b/src/lib/subs/maps.c
index ba699688..903a5897 100644
--- a/src/lib/subs/maps.c
+++ b/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.
- * If OWNER_OR_GOD, the map is for the sector's owner or a deity.
+ * 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.
  */
 static char
 map_char(int type, natid own, int owner_or_god)
diff --git a/src/lib/subs/mission.c b/src/lib/subs/mission.c
index 8ec2cd60..7f7451a2 100644
--- a/src/lib/subs/mission.c
+++ b/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.
- * MISSION is either MI_OSUPPORT or MI_DSUPPORT.
+ * Perform support missions in @x,@y against @victim for @actee.
+ * @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)
diff --git a/src/lib/subs/mtch.c b/src/lib/subs/mtch.c
index a3f89cc6..f551e456 100644
--- a/src/lib/subs/mtch.c
+++ b/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)
diff --git a/src/lib/subs/natarg.c b/src/lib/subs/natarg.c
index d6a57aa5..199ea6cd 100644
--- a/src/lib/subs/natarg.c
+++ b/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.
diff --git a/src/lib/subs/nstr.c b/src/lib/subs/nstr.c
index 37de54fc..ce0c51e7 100644
--- a/src/lib/subs/nstr.c
+++ b/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.
- * TYPE is the context type, a file type.
- * STR is the condition string, in Empire syntax, without the leading
+ * It is an error if there are more than @len conditions.
+ * @type is the context type, a file type.
+ * @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?
- * Return non-zero if and only if IDX is non-negative and VAL is the
- * name of CA[IDX].
- * IDX must have been obtained from nstr_match_ca(VAL, CA).
+ * 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
+ * name of @ca[@idx].
+ * @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)
- * and CA[RGT_IDX] (unless RGT_IDX is negative).  CA may be null when
+ * 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
  * 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 values of selector descriptor CA[IDX], provided IDX is not
- * negative.  CA may be null when IDX is negative.
+ * Match @val in a selector's values, return its (non-negative) value.
+ * Match values of selector descriptor @ca[@idx], provided @idx is not
+ * 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.
- * Return VAL on success, NULL on error.
- * No change if VAL is not an identifier.
- * Else change VAL into symbolic value for selector CA[IDX] if IDX >=
+ * Change @val to resolve identifier to selector.
+ * Return @val on success, NULL on error.
+ * No change if @val is not an identifier.
+ * 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.
- * Return VAL.
- * VAL must be an identifier, and SELVAL must have been obtained from
- * nstr_match_val(VAL, CA0, IDX), where CA = &CA0[IDX].
+ * Change @val to resolve identifier to value @selval for selector @ca.
+ * Return @val.
+ * @val must be an identifier, and @selval must have been obtained from
+ * 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)
diff --git a/src/lib/subs/paths.c b/src/lib/subs/paths.c
index afe5c4c8..db0e4dcc 100644
--- a/src/lib/subs/paths.c
+++ b/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.
- * DIR must be a valid direction.
+ * Map direction @dir to a direction index DIR_STOP..DIR_LAST.
+ * @dir must be a valid direction.
  */
 int
 diridx(char dir)
diff --git a/src/lib/subs/plnsub.c b/src/lib/subs/plnsub.c
index 7c2a5443..37daf508 100644
--- a/src/lib/subs/plnsub.c
+++ b/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.
- * If INPUT_BOMB is not empty, use it, else prompt for more input.
- * Same for INPUT_ESC.
- * If we got a plane argument, initialize *NI_BOMB and *NI_ESC, and
+ * Read planes into *@ni_bomb, and (optional) escorts into *@ni_esc.
+ * If @input_bomb is not empty, use it, else prompt for more input.
+ * Same for @input_esc.
+ * 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 this yields a valid assembly point, read it into *AP_SECT and
- * return AP_SECT.
+ * 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
+ * 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.
- * If planes can land there, set required plane flags in *FLAGSP, and
+ * into @target->ship.  Else read the target sector into @target->sect.
+ * 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_F, P_ESC 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 has any of the capabilities in NOWANTFLAGS.
+ * - 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_E, P_L, P_K in @wantflags, or
+ * - it lacks any of the other capabilities in @wantflags, or
+ * - 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.
- * If MSL find missile types, else non-missile types.
+ * Find plane types that can operate from carrier @sp.
+ * 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?
- * The load consists of N planes, of which NCH are choppers, NXL
- * xlight, NMSL light missiles, and the rest are light fixed-wing
+ * Can a carrier of @sp's type carry this load of planes?
+ * The load consists of @n planes, of which @nch are choppers, @nxl
+ * 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.
- * If it's a chopper, increment *NCH.
- * Else, if it's x-light, increment *NXL.
- * Else, if it's a light missile, increment *MSL.
+ * Increment carrier plane counters for @pp.
+ * If it's a chopper, increment *@nch.
+ * Else, if it's x-light, increment *@nxl.
+ * 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)
diff --git a/src/lib/subs/pr.c b/src/lib/subs/pr.c
index 9c0287eb..e3995659 100644
--- a/src/lib/subs/pr.c
+++ b/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.
- * Format text to send using printf-style FORMAT and optional
+ * Send some text to @p with id @id, line-buffered.
+ * 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.
- * Format text to send using printf-style FORMAT and optional
+ * Send C_FLASH text to @pl.
+ * 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.
- * Format text to send using printf-style FORMAT and optional
+ * Send C_INFORM text to @pl.
+ * 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.
- * BUF is user text.
+ * Send @id text @buf to @pl, line-buffered.
+ * @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.
- * REDIR is UTF-8, but non-ASCII characters can occur only if the
+ * Send redirection request @redir to the current player.
+ * @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.
- * FILE is UTF-8, but non-ASCII characters can occur only if the
+ * Send script execute request @file to the current player.
+ * @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.
- * Read a line of input into BUF[SIZE] and convert it to ASCII.
+ * Send C_FLUSH prompt @prompt to the current player.
+ * 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.
- * Read a line of input into BUF[SIZE], replacing funny characters by
+ * Send C_FLUSH prompt @prompt to the current player.
+ * 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.
- * FORMAT must be a printf-style format string that converts exactly
+ * Print coordinates @x, @y.
+ * @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().
- * Use printf-style FORMAT with the optional arguments.  FORMAT must
+ * Print complete lines to country @cn similar to printf().
+ * Use printf-style @format with the optional arguments.  @format must
  * end with '\n'.
- * If CN is zero, don't print anything.
- * Else, if CN is the current player and we're not in the update,
+ * If @cn is zero, don't print anything.
+ * 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.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * Return length of @dst.
+ * @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.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * Return byte length of @dst.
+ * @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.
- * DST must have space.  If it overlaps SRC, then DST <= SRC must
+ * Return length of @dst.
+ * @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.
- * If S doesn't have that many characters, return its length instead.
+ * 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.
  */
 int
 ufindpfx(char *s, int n)
diff --git a/src/lib/subs/radmap.c b/src/lib/subs/radmap.c
index ffffc4ef..d702ba71 100644
--- a/src/lib/subs/radmap.c
+++ b/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.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
- * Submarines are detected at fraction SEESUB of the range.
+ * Draw a radar map for radar at @cx,@cy.
+ * @eff is the radar's efficiency, @tlev its tech level, @spy its power.
+ * 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.
- * EFF is the radar's efficiency, TLEV its tech level, SPY its power.
+ * Update @owner's bmap for radar at @cx,@cy.
+ * @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.
- * DIST is the distance from the radar, RANGE its range.
- * Country CN is using the radar.
+ * Return character to use in radar maps for sector @SP.
+ * @dist is the distance from the radar, @range its range.
+ * Country @cn is using the radar.
  */
 static char
 rad_char(struct sctstr *sp, int dist, int range, natid cn)
diff --git a/src/lib/subs/show.c b/src/lib/subs/show.c
index a550de8f..b214af15 100644
--- a/src/lib/subs/show.c
+++ b/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.
  */
diff --git a/src/lib/subs/shpsub.c b/src/lib/subs/shpsub.c
index 4211734f..6905da00 100644
--- a/src/lib/subs/shpsub.c
+++ b/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.
- * All ships in SHIP_LIST must be in the same sector.
- * If EXPLICIT is non-zero, this is for an explicit sweep command from
+ * Sweep seamines with engineers in @ship_list for @actor.
+ * All ships in @ship_list must be in the same sector.
+ * 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)
diff --git a/src/lib/subs/snxtitem.c b/src/lib/subs/snxtitem.c
index 953ee303..4e64cf60 100644
--- a/src/lib/subs/snxtitem.c
+++ b/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.
- * The carrier has file type CARRIER_TYPE and uid CARRIER_UID.
+ * Initialize @np to iterate over the items of type @type in a carrier.
+ * 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.
diff --git a/src/lib/subs/trdsub.c b/src/lib/subs/trdsub.c
index e7b6d93d..9f0037d4 100644
--- a/src/lib/subs/trdsub.c
+++ b/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)
diff --git a/src/lib/subs/unitsub.c b/src/lib/subs/unitsub.c
index 7b1d3f0b..b1ead5ca 100644
--- a/src/lib/subs/unitsub.c
+++ b/src/lib/subs/unitsub.c
@@ -464,8 +464,8 @@ unit_move(struct emp_qelem *list)
 }
 
 /*
- * Teleport UNIT to X,Y.
- * If UNIT's mission op-area is centered on it, keep it centered.
+ * Teleport @unit to @x,@y.
+ * 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.
- * Give it to NEWOWN, unless it's zero.
+ * Drop cargo of @unit.
+ * 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.
- * No action if RECIPIENT already owns UNIT.
- * If GIVER is non-zero, inform RECIPIENT and GIVER of the transaction.
+ * Give @unit and its cargo to @recipient.
+ * No action if @recipient already owns @unit.
+ * 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)
diff --git a/src/lib/subs/whatitem.c b/src/lib/subs/whatitem.c
index d9a02e16..d6221427 100644
--- a/src/lib/subs/whatitem.c
+++ b/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)
diff --git a/src/lib/subs/wu.c b/src/lib/subs/wu.c
index cbcf979e..4c84aeab 100644
--- a/src/lib/subs/wu.c
+++ b/src/lib/subs/wu.c
@@ -73,11 +73,11 @@ telegram_is_new(natid to, struct telstr *tel)
 }
 
 /*
- * Send a telegram from FROM to TO.
- * Format text to send using printf-style FORMAT and optional
+ * Send a telegram from @from to @to.
+ * 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.
- * MESSAGE is the text to send, in UTF-8.
- * TYPE is the telegram type.
+ * Send a telegram from @from to @to.
+ * @message is the text to send, in UTF-8.
+ * @type is the telegram type.
  * Return 0 on success, -1 on error.
  */
 int
diff --git a/src/lib/update/bp.c b/src/lib/update/bp.c
index 02bb0c11..fa622a2e 100644
--- a/src/lib/update/bp.c
+++ b/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.
- * COMM must be a tracked item type.
+ * Return the item value tracked in @bp for sector @sp's item @comm.
+ * @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)
 {
diff --git a/src/lib/update/human.c b/src/lib/update/human.c
index 7ac49106..6a924eb0 100644
--- a/src/lib/update/human.c
+++ b/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.
- * BRATE is the birth rate.
- * FOOD is the food available for growing babies.
- * MAXPOP is the population limit.
+ * Return the number of babies born to @adults in @etu ETUs.
+ * @brate is the birth rate.
+ * @food is the food available for growing babies.
+ * @maxpop is the population limit.
  */
 static int
 babies(int adults, int etu, double brate, int food, int maxpop)
diff --git a/src/lib/update/material.c b/src/lib/update/material.c
index 867e49ea..cf60a25b 100644
--- a/src/lib/update/material.c
+++ b/src/lib/update/material.c
@@ -39,10 +39,10 @@
 #include "update.h"
 
 /*
- * Get build materials from sector SP.
- * BP is the sector's build pointer.
- * MVEC[] defines the materials needed to build 100%.
- * PCT is the percentage to build.
+ * Get build materials from sector @sp.
+ * @bp is the sector's build pointer.
+ * @mvec[] defines the materials needed to build 100%.
+ * @pct is the percentage to build.
  * Adjust build percentage downwards so that available materials
  * suffice.  Remove the materials.
  * Return adjusted build percentage.
diff --git a/src/lib/update/produce.c b/src/lib/update/produce.c
index 1757d237..3c55da40 100644
--- a/src/lib/update/produce.c
+++ b/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[].
- * Store amount of work per unit in *COSTP.
+ * Return how much of product @pp can be made from materials @vec[].
+ * 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.
- * If PP depletes a resource, RESOURCE must point to its value.
+ * Return how much of product @pp can be made from its resource.
+ * 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)
diff --git a/src/lib/update/sect.c b/src/lib/update/sect.c
index e6c6269c..48a99d44 100644
--- a/src/lib/update/sect.c
+++ b/src/lib/update/sect.c
@@ -181,8 +181,8 @@ meltitems(int etus, int fallout, int own, short *vec,
 }
 
 /*
- * Do fallout meltdown for sector SP.
- * ETUS above 24 are treated as 24 to avoid *huge* kill offs in
+ * Do fallout meltdown for sector @sp.
+ * @etus above 24 are treated as 24 to avoid *huge* kill offs in
  * large ETU games.
  */
 void
diff --git a/src/server/shutdown.c b/src/server/shutdown.c
index 2ecc9797..bbb95143 100644
--- a/src/server/shutdown.c
+++ b/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.
- * If MINS_FROM_NOW is negative, cancel any pending shutdown instead.
+ * Initiate shutdown in @mins_from_now minutes.
+ * 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.
  */