From 4415fc21544c00996c065501c4261c0d79c1f2b9 Mon Sep 17 00:00:00 2001
From: PatR <rankin@nethack.org>
Date: Sat, 31 Aug 2024 20:30:04 -0700
Subject: [PATCH] revise a couple of recently added comments

---
 src/insight.c | 11 ++++++-----
 src/mkmaze.c  |  4 ++--
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/insight.c b/src/insight.c
index 577b01475..ba74ffaaf 100644
--- a/src/insight.c
+++ b/src/insight.c
@@ -2634,12 +2634,13 @@ vanqsort_cmp(
         }
         res = mcls1 - mcls2; /* class */
         if (res == 0) {
-            /* Riders are in the same class as major demons; group Riders
-               at the start of that class regardless of secondary ordering;
-               res -1 => #1 is a Rider, #2 isn't;
-                    0 => both riders or both major demons;
-                   +1 => #2 is a Rider, #1 isn't */
+            /* Riders are in the same class as major demons, yielding res==0
+               above when both mcls1 and mcls2 are either Riders or demons or
+               one of each; force Riders to be sorted before demons */
             res = is_rider(&mons[indx2]) - is_rider(&mons[indx1]);
+            /* res -1 => #1 is a Rider, #2 isn't;
+                    0 => both Riders or neither;
+                   +1 => #2 is a Rider, #1 isn't */
             if (res)
                 break;
             mlev1 = mons[indx1].mlevel;
diff --git a/src/mkmaze.c b/src/mkmaze.c
index 578f822f8..d485dabdf 100644
--- a/src/mkmaze.c
+++ b/src/mkmaze.c
@@ -1515,8 +1515,8 @@ staticfn void set_wportal(void);
 staticfn void mk_bubble(coordxy, coordxy, int);
 staticfn void mv_bubble(struct bubble *, coordxy, coordxy, boolean);
 
-/* augment the Plane of Water; called from goto_level() when arriving and
-   moveloop_core() when on the level */
+/* augment the Planes of Water (for bubbles) and Air (for clouds); called
+   from goto_level() when arriving and moveloop_core() when on the level */
 void
 movebubbles(void)
 {