Fix and clean up some comments

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

include/empthread.h

@@ -55,7 +55,7 @@
 
 /* Abstract data types */
 
-/* A thread.  */
+/* A thread. */
 typedef struct lwpProc empth_t;
 
 /* A read-write lock, perferring writers */

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
- * implies option HIDDEN.
+ * These are only useful with option LOSE_CONTACT, which implies
+ * option HIDDEN.
  */
 /* Planes spotting and being spotted */
 #define FOUND_FLY	3

include/nsc.h

@@ -63,10 +63,10 @@ enum nsc_type {
     NSC_NATID = NSC_UCHAR	/* nation id */
 };
 
-/* Is TYPE a promoted value type?  */
+/* Is TYPE a promoted value type? */
 #define NSC_IS_PROMOTED(type) (NSC_LONG <= (type) && (type) <= NSC_STRING)
 
-/* Return nsc_type for a signed integer with the same size as TYPE.  */
+/* Return nsc_type for a signed integer with the same size as TYPE. */
 #define NSC_SITYPE(type)				\
     (sizeof(type) == 1 ? NSC_CHAR			\
      : sizeof(type) == sizeof(short) ? NSC_SHORT	\

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
- * verbose if @verbose.
+ * A header identifying the player is prepended to the message.  It is
+ * more verbose if @verbose.
  */
 static int
 sendmessage(struct natstr *to, char *message, int verbose)

src/lib/commands/info.c

@@ -91,7 +91,7 @@ info(void)
     snprintf(filename, sizeof(filename), "%s/%s", infodir, name);
     fp = fopen(filename, "r");
     if (fp == NULL) {
-	/* may be a "partial" request.  */
+	/* may be a "partial" request. */
 	info_dp = opendir(infodir);
 	if (!info_dp) {
 	    pr("Can't open info dir\n");
@@ -300,7 +300,7 @@ info(void)
     snprintf(filename, sizeof(filename) - 1, "%s\\%s", infodir, name);
     fp = fopen(filename, "rb");
     if (fp == NULL) {
-	/* may be a "partial" request.  */
+	/* may be a "partial" request. */
 	HANDLE hDir;
 	WIN32_FIND_DATA fData;
 	strcat(filename, "*");

src/lib/commands/laun.c

@@ -143,7 +143,7 @@ launch_as(struct plnstr *pp)
 	|| !pln_is_in_orbit(&plane)) {
 	pr("No such satellite exists!\n");
 	return RET_FAIL;
-	/* Can be abused to find satellite ids.  Tolerable.  */
+	/* Can be abused to find satellite ids.  Tolerable. */
     }
 
     if (mapdist(pp->pln_x, pp->pln_y, plane.pln_x, plane.pln_y)
@@ -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/mark.c

@@ -95,7 +95,7 @@ display_mark(i_type only_itype, int only_cheapest)
     int cheapest_items[I_MAX + 1];
     i_type i;
 
-    /* Execute trades so report lists only lots that are still available.  */
+    /* Execute trades so report lists only lots that are still available. */
     check_market();
     check_trade();
 

src/lib/commands/move.c

@@ -250,7 +250,7 @@ move(void)
     if (amount > ITEM_MAX - amt_dst) {
 	pr("Only enough room for %d in %s.  The goods will be returned.\n",
 	   ITEM_MAX - amt_dst, xyas(sect.sct_x, sect.sct_y, player->cnum));
-	/* FIXME Not nice.  Move what we can and return the rest.  */
+	/* FIXME Not nice.  Move what we can and return the rest. */
 	getsect(x, y, &sect);
     }
 

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

@@ -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)
 {
@@ -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/filetable.c

@@ -68,7 +68,7 @@ static void plchr_oninit(void *);
 static void lchr_oninit(void *);
 static void nchr_oninit(void *);
 
-/* Number of elements in ARRAY.  */
+/* Number of elements in ARRAY. */
 #define SZ(array) (sizeof(array) / sizeof((array)[0]))
 
 /* Initializers for members flags... */

src/lib/common/hap_fact.c

@@ -54,7 +54,7 @@ hap_fact(struct natstr *tnat, struct natstr *vnat)
     return LIMIT_TO(hap_fact, 0.8, 2.0);
 }
 
-/* Return happiness required to keep NP's citizens happy.  */
+/* Return happiness required to keep NP's citizens happy. */
 double
 hap_req(struct natstr *np)
 {

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
- * pointer to first character not parsed.
+ * On success, store minutes since midnight in *@from_min, *@to_min,
+ * 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

@@ -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)
 {
@@ -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/xdump.c

@@ -301,7 +301,7 @@ xdcolhdr(struct xdstr *xd, struct castr ca[])
     xd->pr("\n");
 }
 
-/* Dump footer for a dump that dumped N objects to XD.  */
+/* Dump footer for a dump that dumped N objects to XD. */
 void
 xdftr(struct xdstr *xd, int n)
 {

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)
@@ -173,7 +173,7 @@ gripe(char *fmt, ...)
     return -1;
 }
 
-/* Make TYPE the current table.  */
+/* Make TYPE the current table. */
 static void
 tbl_start(int type)
 {
@@ -185,7 +185,7 @@ tbl_start(int type)
     idgap_len = 0;
 }
 
-/* End the current table.  */
+/* End the current table. */
 static void
 tbl_end(void)
 {

src/lib/global/constants.c

@@ -169,7 +169,7 @@ float hap_avg = 16.0 * 3.0;
 float edu_avg = 16.0 * 12.0;
 
 
-/* tech build limitations.  */
+/* tech build limitations. */
 float easy_tech = 1.00;		/* amount of tech built with no penality */
 float tech_log_base = 2.0;	/* base of log to take of in-efficient tech */
 

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.
- * If yes, delete that signal from the set of catched signals, and
+ * Test whether a signal from @set has been caught.
+ * 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/lndsub.c

@@ -711,7 +711,7 @@ lnd_check_mines(struct emp_qelem *land_list)
     return stopping;
 }
 
-/* Return whether and why SP would be stuck in SECTP.  */
+/* Return whether and why SP would be stuck in SECTP. */
 enum lnd_stuck
 lnd_check_mar(struct lndstr *lp, struct sctstr *sectp)
 {

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/nstr.c

@@ -202,7 +202,7 @@ nstr_comp(struct nscstr *np, int len, int type, char *str)
     return i + 1;
 }
 
-/* Like strcmp(S1, S2), but limit length of S1 to SZ1 and of S2 to SZ2.  */
+/* Like strcmp(S1, S2), but limit length of S1 to SZ1 and of S2 to SZ2. */
 static int
 strnncmp(char *s1, size_t sz1, char *s2, size_t sz2)
 {

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/pr.c

@@ -436,7 +436,7 @@ prdate(void)
 }
 
 /*
- * Print coordinates @x, @y.
+ * Print coordinates @x,@y.
  * @format must be a printf-style format string that converts exactly
  * two int values.
  */

src/lib/subs/retreat.c

@@ -111,7 +111,7 @@ retreat_ship(struct shpstr *sp, natid own, char code)
 	}
     }
 
-    /* Loop similar to the one in unit_move().  Keep it that way!  */
+    /* Loop similar to the one in unit_move().  Keep it that way! */
     for (i = 0; i < n && !QEMPTY(&list); i++) {
 	/*
 	 * Invariant: shp_may_nav() true for all ships
@@ -211,7 +211,7 @@ retreat_land(struct lndstr *lp, natid own, char code)
 	}
     }
 
-    /* Loop similar to the one in unit_move().  Keep it that way!  */
+    /* Loop similar to the one in unit_move().  Keep it that way! */
     for (i = 0; i < n && !QEMPTY(&list); i++) {
 	/*
 	 * Invariant: lnd_may_nav() true for all land units

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

@@ -43,7 +43,7 @@
 #include "budg.h"
 #include "update.h"
 
-/* Item types we want to track.  */
+/* Item types we want to track. */
 enum bp_item_idx {
     BP_NONE = -1,		/* not tracked */
     BP_MILIT, BP_LCM, BP_HCM,
@@ -59,14 +59,14 @@ struct bp {
     short bp_avail;
 };
 
-/* Map i_type to enum bp_item_idx.  */
+/* Map i_type to enum bp_item_idx. */
 static enum bp_item_idx bud_key[I_MAX + 1] = {
     BP_NONE, BP_MILIT, BP_NONE, BP_NONE,
     BP_NONE, BP_NONE, BP_NONE, BP_NONE, BP_NONE, BP_NONE,
     BP_LCM, BP_HCM, BP_NONE, BP_NONE
 };
 
-/* Return pointer to the element of BP belonging to SP.  */
+/* Return pointer to the element of BP belonging to SP. */
 static struct bp *
 bp_ref(struct bp *bp, struct sctstr *sp)
 {
@@ -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)

src/lib/update/revolt.c

@@ -202,7 +202,7 @@ guerrilla(struct sctstr *sp)
 	return;
     tnat = getnatp(target);
     if (tnat->nat_stat == STAT_UNUSED) {
-	/* target nation has dissolved: che's retire.  */
+	/* target nation has dissolved: che's retire. */
 	logerror("%d Che targeted at country %d retiring", che, target);
 	sp->sct_che = 0;
 	sp->sct_che_target = 0;

src/lib/w32/service.c

@@ -153,7 +153,7 @@ service_ctrl_handler(DWORD Opcode)
 	    return;
 
 	case SERVICE_CONTROL_INTERROGATE:
-	/* Fall through to send current status.  */
+	/* Fall through to send current status. */
 	    break;
 
 	default:

src/lib/w32/w32sockets.c

@@ -84,7 +84,7 @@ w32_set_winsock_errno(void)
     int err = WSAGetLastError();
     WSASetLastError(0);
 
-    /* Map some WSAE* errors to the runtime library's error codes.  */
+    /* Map some WSAE* errors to the runtime library's error codes. */
     switch (err) {
     case WSA_INVALID_HANDLE:
 	errno = EBADF;