diff --git a/include/file.h b/include/file.h
index 59a9b7c1..a0e76766 100644
--- a/include/file.h
+++ b/include/file.h
@@ -63,21 +63,22 @@ struct empfile {
 
     /* User callbacks, may all be null */
     /*
-     * Called after element initialization.  ELT is the element.
+     * Called after element initialization.  @elt is the element.
      * May modify the element.
      */
     void (*oninit)(void *elt);
     /*
-     * Called after read.  ID is the element id, and ELT is the
+     * Called after read.  @id is the element id, and @elt is the
      * element read.  May modify the element.  Modifications are
      * visible to caller of ef_read(), but have no effect on the file.
      */
     void (*postread)(int id, void *elt);
     /*
-     * Called before write.  ID is the element id, OLD is the element
-     * being updated (null unless it is cached) and ELT is the element
-     * being written.  May modify the element.  Modifications will be
-     * visible to caller of ef_write() and are written to the file.
+     * Called before write.  @id is the element id, @old is the
+     * element being updated (null unless it is cached) and @elt is
+     * the element being written.  May modify the element.
+     * Modifications will be visible to caller of ef_write() and are
+     * written to the file.
      */
     void (*prewrite)(int id, void *old, void *elt);
     /*
diff --git a/src/client/play.c b/src/client/play.c
index 13a01363..fbb00fff 100644
--- a/src/client/play.c
+++ b/src/client/play.c
@@ -488,7 +488,7 @@ recv_input(int fd, struct ring *inbuf)
 	return -1;
     if (n == 0) {
 	/*
-	 * Can't put EOF cookie into INBUF here, it may not fit.
+	 * Can't put EOF cookie into @inbuf here, it may not fit.
 	 * Leave it to caller.
 	 */
 	res = 0;
@@ -543,10 +543,10 @@ int
 play(int sock, char *history_file)
 {
     /*
-     * Player input flows from INPUT_FD through recv_input() into ring
-     * buffer INBUF, which drains into SOCK.  This must not block.
-     * Server output flows from SOCK into recv_output().  Reading SOCK
-     * must not block.
+     * Player input flows from @input_fd through recv_input() into
+     * ring buffer @inbuf, which drains into @sock.  This must not
+     * block.  Server output flows from @sock into recv_output().
+     * Reading @sock must not block.
      */
     struct sigaction sa;
     struct ring inbuf;		/* input buffer, draining to SOCK */
diff --git a/src/client/ringbuf.c b/src/client/ringbuf.c
index 3fad2068..68432f59 100644
--- a/src/client/ringbuf.c
+++ b/src/client/ringbuf.c
@@ -39,7 +39,7 @@
 
 /*
  * Initialize empty ring buffer.
- * Not necessary if *R is already zeroed.
+ * Not necessary if *@r is already zeroed.
  */
 void
 ring_init(struct ring *r)
@@ -144,7 +144,7 @@ ring_putm(struct ring *r, void *buf, size_t sz)
 }
 
 /*
- * Discard the N oldest bytes from the ring buffer.
+ * Discard the @n oldest bytes from the ring buffer.
  * It must hold at least that many.
  */
 void
@@ -155,9 +155,9 @@ ring_discard(struct ring *r, int n)
 }
 
 /*
- * Search the ring buffer for zero-terminated string S.
- * Start at the @(n+1)-th byte to be gotten.
- * If found, return the number of bytes in the buffer before S.
+ * Search the ring buffer for zero-terminated string @s.
+ * Start at the (@n+1)-th byte to be gotten.
+ * If found, return the number of bytes in the buffer before @s.
  * Else return -1.
  */
 int
diff --git a/src/lib/common/file.c b/src/lib/common/file.c
index 46417e41..4b5ef527 100644
--- a/src/lib/common/file.c
+++ b/src/lib/common/file.c
@@ -601,7 +601,7 @@ ef_set_uid(int type, void *buf, int uid)
 }
 
 /*
- * Are *A and *B equal, except for timestamps and such?
+ * Are *@a and *@b equal, except for timestamps and such?
  */
 int
 ef_typedstr_eq(struct ef_typedstr *a, struct ef_typedstr *b)
@@ -675,7 +675,7 @@ ef_make_stale(void)
     ef_generation++;
 }
 
-/* Mark copy of an element of table TYPE in BUF fresh. */
+/* Mark copy of an element of table @type in @buf fresh. */
 void
 ef_mark_fresh(int type, void *buf)
 {
diff --git a/src/lib/common/hours.c b/src/lib/common/hours.c
index f19d3dd6..9858202f 100644
--- a/src/lib/common/hours.c
+++ b/src/lib/common/hours.c
@@ -86,7 +86,7 @@ is_daytime_allowed(int dtime, char *times)
 }
 
 /*
- * Can the game played at time T?
+ * Can the game played at time @t?
  */
 int
 gamehours(time_t t)
diff --git a/src/lib/common/pathfind.c b/src/lib/common/pathfind.c
index 10963feb..54593a51 100644
--- a/src/lib/common/pathfind.c
+++ b/src/lib/common/pathfind.c
@@ -99,7 +99,7 @@ static struct pf_map *pf_map;
 
 struct pf_heap {
     int uid;			/* sector uid and */
-    coord x, y;			/* coordinates, uid == XYOFFSET(x, y) */
+    coord x, y;			/* coordinates, @uid == XYOFFSET(@x, @y) */
     double cost;		/* cost from source */
 };
 
@@ -387,11 +387,11 @@ path_find_to(coord dx, coord dy)
 	    ny = y_in_dir(y, DIR_FIRST + i);
 	    nuid = XYOFFSET(nx, ny);
 	    /*
-	     * Cost to enter NX,NY doesn't depend on direction of
-	     * entry.  This X,Y is at least as expensive as any
-	     * previous one.  Therefore, cost to go to NX,NY via X,Y
-	     * is at least as high as any previously found route.
-	     * Skip neighbors that have a route already.
+	     * Cost to enter @nx,@ny doesn't depend on direction of
+	     * entry.  This @x,@y is at least as expensive as any
+	     * previous one.  Therefore, cost to go to @nx,@ny via
+	     * @x,@y is at least as high as any previously found
+	     * route.  Skip neighbors that have a route already.
 	     */
 	    if (!pf_is_unvisited(nuid))
 		continue;
@@ -565,7 +565,7 @@ static double
 cost_land(natid actor, int uid, int mobtype)
 {
     /*
-     * Non-negative cost must not depend on ACTOR, see unit_path().
+     * Non-negative cost must not depend on @actor, see unit_path().
      */
     struct sctstr *sp = (void *)empfile[EF_SECTOR].cache;
 
diff --git a/src/lib/common/rdsched.c b/src/lib/common/rdsched.c
index 67fb325a..bfc1f5c3 100644
--- a/src/lib/common/rdsched.c
+++ b/src/lib/common/rdsched.c
@@ -100,7 +100,7 @@ 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.
+ * @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
@@ -316,7 +316,7 @@ 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.
+ * 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
diff --git a/src/lib/common/xundump.c b/src/lib/common/xundump.c
index 0c85b5a1..a15f1112 100644
--- a/src/lib/common/xundump.c
+++ b/src/lib/common/xundump.c
@@ -195,7 +195,7 @@ tbl_end(void)
 /*
  * 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 *
@@ -450,7 +450,7 @@ rowid_realm(void)
 /*
  * Get the current row's 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 *
diff --git a/src/lib/gen/chance.c b/src/lib/gen/chance.c
index bccca1c9..a58b1c8e 100644
--- a/src/lib/gen/chance.c
+++ b/src/lib/gen/chance.c
@@ -41,7 +41,7 @@
 #include "mt19937ar.h"
 
 /*
- * Return non-zero with probability D.
+ * Return non-zero with probability @d.
  */
 int
 chance(double d)
@@ -72,8 +72,8 @@ round_up_to_pow2(unsigned val)
 }
 
 /*
- * Return a random number in [0..N-1].
- * N must be in [1..2^31-1].
+ * Return a random number in [0..@n-1].
+ * @n must be in [1..2^31-1].
  */
 int
 roll0(int n)
@@ -88,8 +88,8 @@ roll0(int n)
 }
 
 /*
- * Return a random number in [1..N].
- * N must be in [0..2^31-1].
+ * Return a random number in [1..@n].
+ * @n must be in [0..2^31-1].
  */
 int
 roll(int n)
diff --git a/src/lib/subs/getele.c b/src/lib/subs/getele.c
index dcade93d..6a47f6f1 100644
--- a/src/lib/subs/getele.c
+++ b/src/lib/subs/getele.c
@@ -97,7 +97,7 @@ getele(char *recipient, char *buf)
 }
 
 /*
- * If S is a `tilde escape', return its code, else 0.
+ * If @s is a `tilde escape', return its code, else 0.
  * A tilde escape is '~' followed by the code character.
  */
 static int
diff --git a/src/lib/subs/lndsub.c b/src/lib/subs/lndsub.c
index 11d653f0..935ac458 100644
--- a/src/lib/subs/lndsub.c
+++ b/src/lib/subs/lndsub.c
@@ -925,7 +925,7 @@ lnd_pathcost(struct lndstr *lp, double pathcost)
 	effspd *= lp->lnd_effic * 0.01;
 
     /*
-     * The return value must be PATHCOST times a factor that depends
+     * The return value must be @pathcost times a factor that depends
      * only on the land unit.  Anything else breaks path finding.  In
      * particular, you can't add or enforce a minimum cost here.  Do
      * it in sector_mcost().
diff --git a/src/lib/subs/radmap.c b/src/lib/subs/radmap.c
index eb824357..54bf44e3 100644
--- a/src/lib/subs/radmap.c
+++ b/src/lib/subs/radmap.c
@@ -222,7 +222,7 @@ rad_range(int eff, double tlev, int spy)
 }
 
 /*
- * Return character to use in radar maps for sector @SP.
+ * Return character to use in radar maps for sector @sp.
  * @dist is the distance from the radar, @range its range.
  * Country @cn is using the radar.
  */
diff --git a/src/lib/subs/show.c b/src/lib/subs/show.c
index eed35f19..08edeff1 100644
--- a/src/lib/subs/show.c
+++ b/src/lib/subs/show.c
@@ -559,7 +559,7 @@ show_news(int tlev)
 }
 
 /*
- * Show update policy and up to N scheduled updates.
+ * Show update policy and up to @n scheduled updates.
  */
 void
 show_updates(int n)
diff --git a/src/lib/update/anno.c b/src/lib/update/anno.c
index 05c8821e..0cf4e17c 100644
--- a/src/lib/update/anno.c
+++ b/src/lib/update/anno.c
@@ -24,7 +24,7 @@
  *
  *  ---
  *
- *  anno.c: Delete announcements older than ANNO_KEEP_DAYS
+ *  anno.c: Delete announcements older than anno_keep_days
  *
  *  Known contributors to this file:
  *     Ken Stevens, 1995
diff --git a/src/lib/update/plague.c b/src/lib/update/plague.c
index d6f5747e..d2f1f3fc 100644
--- a/src/lib/update/plague.c
+++ b/src/lib/update/plague.c
@@ -103,7 +103,7 @@ infect_people(struct natstr *np, struct sctstr *sp)
 
 /*
  * Given the fact that plague exists, kill off
- * people if in plague state DYING.  Increment
+ * people if in plague state PLG_DYING.  Increment
  * the plague time.  Return "current" plague
  * stage.  No reports generated here anymore.
  */