Fix and clean up some comments

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

include/nat.h

@@ -135,8 +135,8 @@ struct natstr {
 
 /*
  * Number of updates contact lasts for various ways of making contact.
- * These are only useful with option LOSE_CONTACT option, which
+ * These are only useful with option LOSE_CONTACT, which implies
- * implies option HIDDEN.
+ * option HIDDEN.
  */
 /* Planes spotting and being spotted */
 #define FOUND_FLY	3

src/client/ringbuf.c

@@ -90,7 +90,7 @@ ring_peek(struct ring *r, int n)
 
 /*
  * Get and remove the oldest byte from the ring buffer.
- * Return it as unsigned char coverted to int, or EOF if the buffer was
+ * Return it as unsigned char converted to int, or EOF if the buffer was
  * empty.
  */
 int

src/lib/commands/flash.c

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

src/lib/commands/laun.c

@@ -284,7 +284,7 @@ launch_missile(struct plnstr *pp)
 }
 
 /*
- * Launch a satellite.
+ * Launch satellite @pp.
  * Return RET_OK if launched (even when satellite fails),
  * else RET_SYN or RET_FAIL.
  */

src/lib/commands/zdon.c

@@ -40,13 +40,6 @@
  *         Y  = Yes, wants an update.
  *         N  = No, change status to not wanting an update.
  *         C  = Check (the default), check how many want an update.
- *
- * Sets/Unsets a nation flag.
- *
- * Only considers NORMAL, active countries.  No Deities or sanctuaries.
- *
- * After the change, send a message to the "tm" for it to check
- * if an update should occur.
  */
 
 #include <config.h>

src/lib/common/cargo.c

@@ -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 @lp carries land units, return the uid of the first one, else -1.
  */
 int
 lnd_first_on_land(struct lndstr *lp)
@@ -400,6 +400,7 @@ nuk_on_plane(struct plnstr *pp)
 
 /*
  * Return length of a carrier's cargo list for file type @cargo_type.
+ * Use carrier @uid of type @type.
  */
 int
 unit_cargo_count(int type, int uid, int cargo_type)

src/lib/common/file.c

@@ -976,7 +976,7 @@ ef_check(int type)
 }
 
 /*
- * Ensure table contains element @id.
+ * Ensure table @type contains element @id.
  * If necessary, extend it in steps of @count elements.
  * Return non-zero on success, zero on failure.
  */

src/lib/common/hours.c

@@ -65,7 +65,8 @@ is_wday_allowed(int wday, char *days)
 }
 
 /*
- * Is day time @dtime (minutes since midnight) allowed by restriction @times?
+ * Is day time @dtime allowed by restriction @times?
+ * @dtime is in minutes since midnight.
  * If @times is not empty, it lists the allowed day time ranges.  See
  * daytime_range() for syntax.
  */
@@ -171,8 +172,8 @@ daytime(char *str, int *min)
 
 /*
  * Parse a day time range in @str.
- * On success store minutes since midnight in *@from and *@to, return
+ * On success, store minutes since midnight in *@from_min, *@to_min,
- * pointer to first character not parsed.
+ * and return pointer to first character not parsed.
  * Else return NULL.
  * Format is HOUR:MINUTE-HOUR:MINUTE.  Initial whitespace is ignored.
  */

src/lib/common/mailbox.c

@@ -92,7 +92,7 @@ tel_read_header(FILE *fp, char *mbox, struct telstr *tel)
  * @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.
  */

src/lib/common/pathfind.c

@@ -328,7 +328,7 @@ 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).
+ * The cost to enter the sector with uid ID is @cost(@actor, ID).
  * Negative value means the sector can't be entered.
  */
 static void
@@ -413,10 +413,11 @@ path_find_to(coord dx, coord dy)
 }
 
 /*
- * Write route from @sx,@sy to @dx,@dy to @buf[@bufsiz], return its length.
+ * Write route from @sx,@sy to @dx,@dy to array @buf[@bufsiz].
  * 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.
+ * Return length of the (untruncated) route.
  */
 size_t
 path_find_route(char *buf, size_t bufsz,

src/lib/common/xundump.c

@@ -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)

src/lib/lwp/sig.c

@@ -39,7 +39,7 @@
 #include "lwpint.h"
 
 /*
- * Signals catched so far.
+ * Signals caught so far.
  * Access only with signals blocked!
  */
 static sigset_t LwpSigCatched;
@@ -83,8 +83,8 @@ lwpCatchAwaitedSig(int sig)
 }
 
 /*
- * Test whether a signal from @set has been catched.
+ * Test whether a signal from @set has been caught.
- * If yes, delete that signal from the set of catched signals, and
+ * If yes, delete that signal from the set of caught signals, and
  * return its number.
  * Else return 0.
  */

src/lib/subs/control.c

@@ -67,7 +67,7 @@ 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.
+ * @list would abandon the 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.
  */

src/lib/subs/getstarg.c

@@ -38,7 +38,8 @@
 
 /*
  * Get string argument.
- * If @input is not empty, use it, else prompt for more input using @prompt.
+ * If @input is not empty, use it.
+ * Else prompt for more input using @prompt.
  * Copy input to @buf[1024].
  * Return @buf on success, else NULL.
  */

src/lib/subs/landgun.c

@@ -145,7 +145,8 @@ shp_dchrg(struct shpstr *sp)
 
 /*
  * Fire torpedo from ship @sp.
- * Use ammo and mobility, resupply if necessary.
+ * Use ammo, resupply if necessary.
+ * Use mobility if @usemob is non-zero.
  * Return damage if the ship fires, else -1.
  */
 int
@@ -203,7 +204,7 @@ lnd_fire(struct lndstr *lp)
 }
 
 /*
- * Sabotage with land unit @lp.
+ * Sabotage with land unit @lp, target has @item[] commodities.
  * Use ammo.
  * Return damage if the land unit sabotages, else -1.
  */
@@ -293,7 +294,7 @@ shp_torp_hitchance(struct shpstr *sp, int range)
 }
 
 /*
- * Return firing range for land unit @sp.
+ * Return firing range for land unit @lp.
  */
 double
 lnd_fire_range(struct lndstr *lp)

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 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)

src/lib/subs/natarg.c

@@ -44,7 +44,8 @@
 
 /*
  * 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 +80,8 @@ natargp(char *arg, char *prompt)
 
 /*
  * Get nation argument.
- * If @arg is not empty, use it, else prompt for input using @prompt.
+ * If @arg is not empty, use it.
+ * Else prompt for input using @prompt.
  * If no input is provided, return -1.
  * If the argument identifies a country, return its number.  getnatp()
  * can be assumed to succeed for this number.

src/lib/subs/plnsub.c

@@ -82,7 +82,8 @@ get_planes(struct nstr_item *ni_bomb, struct nstr_item *ni_esc,
 
 /*
  * Get assembly point argument.
- * If @input is not empty, use it, else prompt for more input using @prompt.
+ * If @input is not empty, use it.
+ * Else prompt for more input using @prompt.
  * If this yields a valid assembly point, read it into *@ap_sect and
  * return @ap_sect.
  * Else complain and return NULL.

src/lib/subs/whatitem.c

@@ -36,7 +36,8 @@
 
 /*
  * 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 *

src/lib/update/bp.c

@@ -87,7 +87,9 @@ 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 item value tracked in @bp for sector @sp's item @comm to @amount.
+ */
 void
 bp_put_item(struct bp *bp, struct sctstr *sp, i_type comm, int amount)
 {
@@ -119,7 +121,7 @@ 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 to @amount. */
 void
 bp_put_avail(struct bp *bp, struct sctstr *sp, int amount)
 {

src/lib/update/produce.c

@@ -232,7 +232,7 @@ prod_resource_limit(struct pchrstr *pp, unsigned char *resource)
 /*
  * 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 level affecting production.
  */
 double
 prod_eff(int type, float level)