Add explanatory comments.

diff --git a/NEWS.adoc b/NEWS.adoc
index b879e1742d8a55a51ba6aea84d4e06554043c282..c390e7e54d9ecada6abf9900cf72f949485c7b70 100644 (file)
--- a/NEWS.adoc
+++ b/NEWS.adoc
@@ -2,7 +2,7 @@
 // SPDX-FileCopyrightText: Eric S. Raymond <esr@thyrsus.com>
 // SPDX-License-Identifier: CC-BY-4.0
 
-Reoisitory head::
+Repository head::
   Savefiles now have an identifying magic cookie at the front.
   Resume detects if a save has incompatible endianness.
 

diff --git a/advent.h b/advent.h
index cb2b71b62ea6f4273e77b6fcf31396b1d865eb0e..0cbe7fb01648d73d01153f33e9edf10d2c60f237 100644 (file)
--- a/advent.h
+++ b/advent.h
@@ -48,12 +48,27 @@
 #define IS_FIXED -1
 #define IS_FREE 0
 
-/* PROP_STASHED maps a state property value to a negative range, where the object
- * cannot be picked up but the value can be recovered later. */
 #ifndef FOUNDBOOL
-/* PROP_STASHED needs ro avoid colliding with -1,
- * which has its own meaning as STATE_NOTFOUND. */
-#define PROP_STASHED(obj)      (STATE_NOTFOUND - game.objects[obj].prop)
+/* (ESR) It is fitting that translation of the original ADVENT should
+ * have left us a maze of twisty little conditionals that resists all
+ * understanding.  Setting and use of what is now the per-object state
+ * member (which used to be an array of its own) is our mystery. This
+ * state tangles together information about whether the object is a
+ * treasure, whether the player has seen it yet, and its activation
+ * state.
+ *
+ * Things we think we know:
+ *
+ * STATE_NOTFOUND is only set on treasures. Non-treasures start the
+ * game in STATE_FOUND.
+ *
+ * PROP_STASHED is supposed to map a state property value to a
+ * negative range, where the object cannot be picked up but the value
+ * can be recovered later.  Various objects get this peoperty when
+ * the cave starts to close. On;y seems to be signifucant for the bird 
+ * and readable objects, notably the clam/oyster - but the code around
+ * those test is difficult to read. */
+#define PROP_STASHED(obj)      (-1 - game.objects[obj].prop)
 #define PROP_IS_STASHED(obj)   (game.objects[obj].prop < STATE_NOTFOUND)
 #define PROP_IS_NOTFOUND(obj)  (game.objects[obj].prop == STATE_NOTFOUND)
 #define PROP_IS_FOUND(obj)     (game.objects[obj].prop == STATE_FOUND)
@@ -63,6 +78,13 @@
 #define PROP_IS_NOTFOUND2(g, o)        (g.objects[o].prop == STATE_NOTFOUND)
 #define PROP_IS_INVALID(val)   (val < -MAX_STATE - 1 || val > MAX_STATE)
 #else
+/* (ESR) Only the boldest of adventurers will explore here.  This
+ * alternate set of definitions for the macros above was an attempt to
+ * break from out of the state encoding a per-object "found" member
+ * telling whether or not the player has seen the object. These is one
+ * accompanying change in misc.c.  What's broken when you try to use
+ * thus is PROP_IS_STASHED_OR_UNSEEN.
+ */
 #define PROP_STASHED(obj)      (-game.objects[obj].prop)
 #define PROP_IS_STASHED(obj)   (game.objects[obj].prop < 0)
 #define PROP_IS_NOTFOUND(obj)  (!game.objects[obj].found)

diff --git a/main.c b/main.c
index 92ab1b16ecb87219e08da0055c48442f33c0999b..c688018d3e97ec31ef9b1f4dfc5b6da52205313b 100644 (file)
--- a/main.c
+++ b/main.c
@@ -917,6 +917,10 @@ static void listobjects(void)
                 obj = obj - NOBJECTS;
             if (obj == STEPS && TOTING(NUGGET))
                 continue;
+           /* (ESR) Warning: it looks like you could get away with
+            * running this code only on objects with the treasure
+            * property set. Nope.  There is mystery here.
+            */
             if (PROP_IS_STASHED_OR_UNSEEN(obj)) {
                 if (game.closed)
                     continue;

diff --git a/misc.c b/misc.c
index 0d540c65d7518eadf448f1941f9e2f7b16936a7a..f6a37f71a05d66fb5a59ab2c296fe4836b35500c 100644 (file)
--- a/misc.c
+++ b/misc.c
@@ -600,8 +600,10 @@ void put(obj_t object, loc_t where, int pval)
  *  negated game.prop values for the repository objects. */
 {
     move(object, where);
+    /* (ESR) Read this in combination with the macro defintions in advebt.h.
+     */
 #ifndef FOUNDBOOL
-    game.objects[object].prop = (-1) - pval;;  // Needs to stay synchronized with PROP_STASHED
+    game.objects[object].prop = (-1) - pval;   // Needs to stay synchronized with PROP_STASHED
 #else
     game.objects[object].prop = - pval;;       // Needs to stay synchronized with PROP_STASHED
     game.objects[object].found = true;