From e50ec526f5867b6d6c13114ebee888f0b7afa98f Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@pond.sub.org>
Date: Sat, 13 Jan 2007 18:08:49 +0000
Subject: [PATCH] Document.

(BP_CIVIL, BP_SHELL, BP_GUN): These were used write-only.  Remove.
(bud_key): Update accordingly.

(bp_item_idx): enumeration type for the bp_item[] indexes.  Use where
appropriate.

(bp_get_item): Oops on access to an item that is not tracked.
---
 src/lib/update/bp.c | 46 +++++++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/src/lib/update/bp.c b/src/lib/update/bp.c
index aede6f4d..43534566 100644
--- a/src/lib/update/bp.c
+++ b/src/lib/update/bp.c
@@ -25,76 +25,98 @@
  *
  *  ---
  *
- *  bp.c: Functions for build pointer (bp) handling
+ *  bp.c: The `build pointer' (bp) map
  * 
  *  Known contributors to this file:
  *     Ville Virrankoski, 1996
  *     Markus Armbruster, 2007
  */
 
+/*
+ * Some commands call update functions to simulate the update.
+ * Naturally, these functions must not change game state then.
+ * Instead, they track values separate data structure, namely the bp
+ * map.
+ */
+
 #include <config.h>
 
 #include "budg.h"
 #include "update.h"
 
-enum {
-    BP_NONE = -1,
-    BP_CIVIL, BP_MILIT, BP_SHELL, BP_GUN, BP_LCM, BP_HCM,
+/* Item types we want to track.  */
+enum bp_item_idx {
+    BP_NONE = -1,		/* not tracked */
+    BP_MILIT, BP_LCM, BP_HCM,
     BP_MAX = BP_HCM
 };
 
+/*
+ * Stuff to track for a sector.
+ * A bp map is an array of these.
+ */
 struct bp {
     short bp_item[BP_MAX + 1];
     short bp_avail;
 };
 
-static int bud_key[I_MAX + 1] = {
-    BP_CIVIL, BP_MILIT, BP_SHELL, BP_GUN,
+/* 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.  */
 static struct bp *
 bp_ref(struct bp *bp, struct sctstr *sp)
 {
     return &bp[sp->sct_x + sp->sct_y * WORLD_X];
 }
 
+/*
+ * 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)
 {
-    int idx = bud_key[comm];
+    enum bp_item_idx idx = bud_key[comm];
 
-    if (idx < 0)
+    if (CANT_HAPPEN(idx < 0))
 	return sp->sct_item[comm];
     return bp_ref(bp, sp)->bp_item[idx];
 }
 
+/* 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)
 {
-    int idx = bud_key[comm];
+    enum bp_item_idx idx = bud_key[comm];
 
     if (idx >= 0)
 	bp_ref(bp, sp)->bp_item[idx] = amount;
 }
 
+/* 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.  */
 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.  */
 void
 bp_set_from_sect(struct bp *bp, struct sctstr *sp)
 {
-    int idx;
+    enum bp_item_idx idx;
     struct bp *p = bp_ref(bp, sp);
     i_type i;
 
@@ -106,6 +128,10 @@ bp_set_from_sect(struct bp *bp, struct sctstr *sp)
     p->bp_avail = sp->sct_avail;
 }
 
+/*
+ * Return a new bp map.
+ * Caller should pass it to free() when done with it.
+ */
 struct bp *
 bp_alloc(void)
 {