Change comment style to use @foo rather than FOO

... when referring to a function's parameter or a struct/union's
member.

The idea of using FOO comes from the GNU coding standards:

    The comment on a function is much clearer if you use the argument
    names to speak about the argument values.  The variable name
    itself should be lower case, but write it in upper case when you
    are speaking about the value rather than the variable itself.
    Thus, "the inode number NODE_NUM" rather than "an inode".

Upcasing names is problematic for a case-sensitive language like C,
because it can create ambiguity.  Moreover, it's too much shouting for
my taste.

GTK-Doc's convention to prefix the identifier with @ makes references
to variables stand out nicely.  The rest of the GTK-Doc conventions
make no sense for us, however.

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

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

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)

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.

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)

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