Edited some docstrings, comments, and whitespace.

Author: Kodiologist

simalq/cmdline.hy

@@ -1,3 +1,6 @@
+"The command-line interface."
+
+
 (require
   hyrule [unless])
 (import

simalq/color.hy

@@ -1,3 +1,6 @@
+"Color definitions."
+
+
 (setv
 
   by-name (dfor

simalq/commands.hy

@@ -1,3 +1,6 @@
+"Interface and logic for player commands and actions."
+
+
 (require
   hyrule [case ecase ebranch do-n unless]
   simalq.macros [defdataclass])
@@ -20,7 +23,7 @@
   "Something the player wants to do, translated from user input.")
 
 (defdataclass Action [Command]
-  "A discrete effect that the player can have on the gamestate.")
+  "A discrete effect that the player can have on the game state.")
 (defdataclass Wait [Action]
   "Do nothing, passing your turn (or, more precisely, passing
   one opportunity for an action).")
@@ -60,7 +63,6 @@
   wait key) to get info on a tile under the cursor, and any other key
   to exit look mode. If there's more than one tile on the selected
   square, you'll be prompted to choose one when you try to get info.")
-
 (defdataclass ShiftHistory [Command]
   "{details}"
   ; Undo or redo.
@@ -89,7 +91,6 @@
   None)
 
 
-
 (defn do-command [cmd]
   "This function is only for commands that aren't actions; see
   `do-action` for actions."
@@ -187,16 +188,19 @@
       (ecase G.player.game-over-state
         'dead "You're dead"
         'won "You won the game")))))
-  (when (and (.player-has? StatusEffect.Para) (is-not (type action) Wait))
+  (when (and
+      (.player-has? StatusEffect.Para)
+      (is-not (type action) Wait))
     (raise (CommandError "You're paralyzed. You can only wait for it to pass.")))
 
   (ebranch (in (type action) it)
 
     [Wait]
-      ; Nothing to do. This action should always succeed.
+      ; Nothing to do. This action should always be allowed.
       None
 
     [Walk UseControllableTeleporter] (do
+
       (defn pat [pos]
         "`at`, but excluding tiles we should ignore due to passwall."
         (gfor
@@ -206,21 +210,25 @@
             tile.passwallable
             (.player-has? StatusEffect.Pass)))
           tile))
+
       (setv d action.direction)
       (setv [target wly] (walkability G.player.pos d :monster? F))
       (when (= wly 'out-of-bounds)
         (raise (CommandError "The border of the dungeon blocks your movement.")))
       (when (= wly 'blocked-diag)
         (raise (CommandError "That diagonal is blocked by a neighbor.")))
+
       (for [tile (pat target)]
         (when (.hook-player-bump tile G.player.pos)
           (return)))
       (when (= wly 'bump)
         (raise (CommandError "Your way is blocked.")))
+
       (for [tile (pat G.player.pos)]
         (.hook-player-walk-from tile target))
       (for [tile (pat target)]
         (.hook-player-walk-to tile G.player.pos))
+
       ; No exceptions have stopped us, so go.
       (setv pos-was G.player.pos)
       (.move G.player target)
@@ -231,6 +239,7 @@
           (return))))
 
     [Shoot] (do
+
       (setv
         d action.direction
         target G.player.pos
@@ -239,6 +248,7 @@
       (when G.player.magic-arrows
        (setv magic? T)
        (-= G.player.magic-arrows 1))
+
       (defn animate []
         (flash-map :flash-time-s .1
           G.player.pos
@@ -247,6 +257,7 @@
             color.flash-player-shot-mundane)
           targets
           {}))
+
       (do-n G.rules.reality-bubble-size
         (setv target (+ target d))
         (unless target
@@ -277,8 +288,8 @@
               (unless (and magic? (!= tile.pos target))
                 (return)))
             tile.blocks-player-shots
-              ; The arrow won't be able to leave this square, although
-              ; it can affect other tiles in the square.
+              ; The arrow can't leave this square, although it can
+              ; affect other tiles in the square.
               (setv blocked T)))
         (when blocked
           (animate)
@@ -302,6 +313,7 @@
           (when target
             (raise (CommandError "That item can't use a target.")))
           (.use item)))
+      ; All usable items are destroyed after one use.
       (setv (get G.player.inventory action.item-ix) None))))
 
 
@@ -312,10 +324,12 @@
   should then end.
 
   Return a selected `Pos` or `None`."
+
   (setv focus G.player.pos)
   (hy.I.simalq/main.io-mode
     :draw (fn []
-      (hy.I.simalq/main.print-main-screen focus :status-bar F :tile-list 'nonpickable))
+      (hy.I.simalq/main.print-main-screen
+        focus :status-bar F :tile-list 'nonpickable))
     :on-input (fn [key]
       (nonlocal focus)
       (setv dir-v (hy.I.simalq/keyboard.read-dir-key key))

simalq/game_state.hy

@@ -121,7 +121,8 @@
       ; changing, such as monsters moving around.
     level-n None
       ; An integer indicating the level we're currently playing.
-      ; Numbered starting from 1.
+      ; Numbered starting from 1, so `(get G.quest.levels n)` is
+      ; counted as level `(- n 1)`.
     score 0
       ; How many points the player has accumulated.
     turn-n 0
@@ -146,7 +147,7 @@
     reality-bubble-size 6
       ; The reality bubble is the (Chebyshev) radius around the
       ; player in which monsters etc. get to act. It's a square
-      ; spanning `2 * reality-bubble-size + 1` map squares on each
+      ; spanning `(+ (* 2 reality-bubble-size) 1)` map squares on each
       ; side, with the player in the center.
     player-hp-factor (f/ 1)
       ; Multiplies the player's starting HP and healing.
@@ -179,9 +180,8 @@
       ; Damage per turn (to the player) from poisonous fountains.
     dainty-monsters T])
       ; Whether monsters will only step on empty floor (with some
-      ; exceptions, like spiders walking on webs). Otherwise,
-      ; monsters obey similar rules as the player does regarding
-      ; blocking tiles.
+      ; exceptions, like spiders walking on webs). Otherwise, monsters
+      ; can move through items and some kinds of scenery.
 
 
 (setv G (Global))

simalq/geometry.hy

@@ -1,3 +1,6 @@
+"Types for level geometry and functions to operate on them."
+
+
 (require
   hyrule [unless do-n]
   simalq.macros [defdataclass defmeth])
@@ -17,8 +20,8 @@
       ; Booleans.
     data
       ; A tuple of tuples representing the squares of the map. Each
-      ; tile is itself a list representing a stack of tiles on that
-      ; square. An empty stack means that the tile has only floor.
+      ; square is itself a list representing a stack of tiles. An
+      ; empty stack means that the square has only plain floor.
     width height
       ; Cached map dimensions for speed.
     each-turn
@@ -51,8 +54,8 @@
   :fields [name x y]
   :frozen T)
 ((fn []
-  ; Define the direction constants (`Direction.N`, `.NE`, etc.)
-  ; and collections thereof (`Direction.orths`, `.diags`, `.all`).
+  ; Define the direction constants (`Direction.N`, `.NE`, etc.) and
+  ; related conveniences (e.g., `Direction.orths`).
   (setv Direction.orths (tuple (map Direction
     ["north" "east" "south" "west"]
     [0       1       0      -1]
@@ -211,7 +214,7 @@
     p)))
 
 (defn burst-size [size [article? True]]
-  "Describes the size of a `burst`."
+  "Describe the size of a `burst` in prose."
   (setv n (- (* 2 size) 1))
   (.format "{}{}-by-{} burst"
     (if article?

simalq/macros.hy

@@ -3,6 +3,8 @@
 
 
 (defmacro defdataclass [class-name superclasses #* rest]
+  "Syntactic sugar for common uses of data classes."
+
   (setv   rest (list rest)  docstring [])
   (when (and rest (isinstance (get rest 0) hy.models.String))
     (.append docstring (.pop rest 0)))
@@ -172,9 +174,11 @@
     #** (if p-kwargs {p-kwargs collected-kwargs} {})))
 
 (defn parse-params [params]
+  "A subroutine for `defmacro-kwargs` and `match-params`."
   (import
     funcparserlib.parser [maybe many]
     hy.model-patterns [SYM FORM sym brackets pexpr])
+
   (setv msym (>> SYM hy.mangle))
   (defn pvalue [root wanted]
     (>> (pexpr (+ (sym root) wanted)) (fn [x] (get x 0))))

simalq/quest_definition/__init__.hy

@@ -70,8 +70,8 @@ quest definitions from other files in this directory."
       ; The requested tiles are placed in a line east of the player
       ; start.
     [map None]
-      ; Overrides `width`, `height`, `tiles`, and possibly
-      ; `player-start` if provided.
+      ; A string passed to `parse-text-map`. It overrides `width`,
+      ; `height`, `tiles`, and possibly `player-start` if provided.
     [map-marks #()]
     [title None]
     [next-level None]
@@ -119,6 +119,7 @@ quest definitions from other files in this directory."
         (setv player-start #(x y))
       (= mapsym ". ")
         None
+      ; A few mapsyms have a default associated tile for convenience.
       (= mapsym "██")
         (mk-tile p "wall")
       (= mapsym "> ")

simalq/save_load.hy

@@ -1,3 +1,12 @@
+"Code for saving games and loading saved games. Each saved game is a
+ZIP archive with two members:
+- `state.pkl`, a pickled `Global` object
+- `meta.json`, a JSON file of metadata."
+
+;; --------------------------------------------------------------
+;; * Imports
+;; --------------------------------------------------------------
+
 (require
   hyrule [unless])
 (import

simalq/strings.hy

@@ -1,3 +1,6 @@
+"Lists of strings to pick from pseudorandomly."
+
+
 (setv meal-messages #(
   "Finally, some good pizza."
   "Macaroni with the chicken shtrips. Ugh!"

simalq/util.hy

@@ -25,6 +25,7 @@
   (range a (+ b step) step))
 
 (defn sign [x]
+  "N.B. This function returns 0 for -0.0, and raises `TypeError` for NaN."
   (cond
     (< x 0) -1
     (> x 0)  1
@@ -114,16 +115,16 @@
 
 
 (defclass DamageType [Enum] (setv
-  ; These only apply to damage against monsters
+  ; These only apply to damage against monsters.
   PlayerMelee   "sword attacks"
   MundaneArrow  "mundane arrows"
   MagicArrow    "magic arrows"
   Fire          "fire"
-  ; These only apply to damage against the player
+  ; These only apply to damage against the player.
   MonsterMelee  "monsters' melee attacks"
   MonsterShot   "monsters' shots"
   Trap          "traps"
-  ; These are equal-opportunity
+  ; These are equal-opportunity.
   Poison        "poison"
   DeathMagic    "death magic"))
 
@@ -145,6 +146,7 @@
     (bool (get G.player.status-effects @)))
 
   (defmeth add [duration]
+    "Give the player this status effect for the given duration."
     (when (and (@bad?) (.player-has? StatusEffect.Prot))
       ; Protection prevents harmful effects.
       (return))