Tidy up object, thing, and room modules with proper documentation

Author: PPKFS

yaifl-core/src/Yaifl/Object/Kind.hs

@@ -1,15 +1,22 @@
 {-|
 Module      : Yaifl.Object.Kind
-Copyright   : (c) Avery 2023-2024
+Copyright   : (c) Avery 2023-2026
 License     : MIT
 Maintainer  : ppkfs@outlook.com
 
-A game object (a thing or a room).
+Game objects represent the fundamental building blocks of the game world,
+encompassing both things (portable objects) and rooms (environmental locations).
+
+This module defines the core `Object` data structure and its supporting components:
+
+- `Object`: The primary data structure combining identification, naming, and kind-specific behaviour
+- `ObjectKind`: Classification system for object kinds (distinct from Haskell types)
+- `Timestamp`: Creation and modification tracking for objects
+- `Name*` types: Linguistic properties controlling article usage and pluralisation
+- `IsObject`: Typeclass for thing/room classification
 -}
 
 module Yaifl.Object.Kind (
-  -- * Pointed sets
-  Pointed(..)
   -- * Objects
   -- ** Components
   , NamePlurality(..)
@@ -28,28 +35,50 @@ import Yaifl.Prelude
 import Yaifl.Entity
 import Yaifl.WorldModel (WMText)
 
--- | If the object has a pluralised name.
+-- | Whether the object's name changes when pluralised.
+-- `SingularNamed` objects like "key" become "keys" when plural.
+-- `PluralNamed` objects like "sheep" remain "sheep" when plural.
 data NamePlurality = SingularNamed | PluralNamed
   deriving stock (Show, Eq, Ord, Bounded, Enum, Generic, Read)
 
--- | If the object should have an indefinite article or not.
+-- | Whether the object's name is a proper noun or common noun.
+-- `Proper` names (e.g., "John", "London") don't use articles.
+-- `Improper` names (e.g., "key", "door") may use indefinite articles.
 data NameProperness = Improper | Proper
   deriving stock (Show, Eq, Ord, Bounded, Enum, Generic, Read)
 
--- | If the object should have an indefinite article or not.
+-- | Whether the object's name is accessible to the command parser.
+-- `PrivatelyNamed` objects cannot be referred to by their given name in commands.
+-- They can only be referenced via their `understandAs` properties.
+-- `PubliclyNamed` objects can be referred to directly by their name in commands.
 data NamePrivacy = PrivatelyNamed | PubliclyNamed
   deriving stock (Show, Eq, Ord, Bounded, Enum, Generic, Read)
 
--- | See also `Yaifl.Metadata.typeDAG`. An object type is just a string that has some relations to other types.
--- there is no data or polymorphism connected to a type, so it's very possible to call something a supporter without
--- having some supporter properties.
+-- | A classification type for game objects, representing their role or category in the game world.
+-- ObjectKinds form a directed acyclic graph (see `Yaifl.Metadata.typeDAG`) where relationships
+-- between types are explicitly defined rather than implied through inheritance or polymorphism.
+--
+-- This design allows flexible classification: an object can be classified as a "supporter" without
+-- requiring any specific data structure or behavioural implementation. The type system is purely
+-- descriptive, enabling runtime type checking and hierarchical organisation without code coupling.
+--
+-- Examples of object kinds include: "container", "supporter", "door", "person", "scenery".
+--
+-- The `ObjectKind` is a simple wrapper around `Text` for type safety and to enable specific
+-- instances and operations related to the type system.
 newtype ObjectKind = ObjectKind
   { unObjectKind :: Text
   } deriving stock (Eq, Show)
     deriving newtype (Read, Ord, IsString, Monoid, Semigroup)
 
--- | A `Timestamp` is used to date events that modify, add, or remove objects.
--- Currently these aren't...used for anything.
+-- | A `Timestamp` tracks when objects are created or modified.
+-- Timestamps do not necessarily correspond to game turns, but rather to state update ticks.
+-- If an object's timestamp is older than the current game state, it indicates the object
+-- may be out of date and should be refreshed.
+--
+-- Currently implemented but not actively used in game logic, this field provides
+-- infrastructure for potential future features such as object aging, undo functionality,
+-- or temporal queries.
 newtype Timestamp = Timestamp
   { unTimestamp :: Int
   } deriving stock (Show, Read, Generic)
@@ -69,7 +98,7 @@ data Object wm objData objSpecifics = Object
   , objectType :: ObjectKind
   , creationTime :: Timestamp
   , modifiedTime :: Timestamp
-  , specifics :: objSpecifics -- ^ A @vanilla@ object has no specific additional information; this is a @Pointed@ constraint.
+  , specifics :: objSpecifics -- ^ Kind-specific data (e.g., door mechanics, container contents)
   , objectData :: objData -- ^ `ThingData`, `RoomData`, or `Either ThingData RoomData`.
   } deriving stock (Generic)
 
@@ -91,7 +120,7 @@ objectEquals = (. getEntity) . (==) . getEntity
 instance Eq (Object wm d s) where
   (==) = objectEquals
 
--- | Maybe I'll need this instance for something or other?
+-- | Order objects by creation time for chronological sorting.
 instance Ord (Object wm d s) where
   compare = (. creationTime) . compare . creationTime
 
@@ -113,7 +142,13 @@ instance Bitraversable (Object wm) where
         s' = g (specifics o)
     in (\d s -> o & #objectData .~ d & #specifics .~ s) <$> d' <*> s'
 
--- | If something is a thing or a room.
+-- | Typeclass for determining whether an object is a thing or a room.
+-- This provides a uniform interface for thing/room classification across
+-- different object representations.
+--
+-- The classification follows the convention established in `Yaifl.Entity`:
+-- positive entity IDs represent `Yaifl.Thing.Kind.Thing`s, while negative
+-- entity IDs represent `Yaifl.Room.Kind.Room`s.
 class IsObject o where
   isThing :: o -> Bool
 

yaifl-core/src/Yaifl/Room/Kind.hs

@@ -1,18 +1,55 @@
+{-|
+Module      : Yaifl.Room.Kind
+Copyright   : (c) Avery 2023-2026
+License     : MIT
+Maintainer  : ppkfs@outlook.com
+
+Rooms represent environmental locations in the game world that contain objects,
+provide spatial context, and define the game's geography.
+
+This module defines the `Room` type and its associated data structures:
+
+- `Room`: The core room type wrapping `Object` with room-specific data
+- `RoomData`: Comprehensive properties for room behaviour and state
+- `Connection`: Room-to-room connections with direction and explicitness (author-created vs implied)
+- `MapConnections`: Direction-based connection mapping
+- Functions for querying room properties and managing room state
+
+See also:
+- `Yaifl.Object.Kind` for the base Object type
+- `Yaifl.Enclosing.Kind` for enclosing functionality
+- `Yaifl.Tag` for the tagging system used by `tagRoomEntity`
+- `Yaifl.Metadata` for game state management used by `updateFirstRoom`
+-}
+
 module Yaifl.Room.Kind
-  ( ConnectionExplicitness(..)
+  ( -- * Connection types
+    ConnectionExplicitness(..)
   , Connection(..)
   , MapConnections(..)
-  -- ** Rooms
+
+    -- * Room components
   , ContainingRegion(..)
   , Darkness(..)
   , RoomData(..)
   , IsVisited(..)
   , blankRoomData
+
+    -- * Room type
   , Room(..)
+
+    -- * Entity tagging
   , tagRoomEntity
+
+    -- * Default IDs
   , voidID
-  , isNotVisited
+
+    -- * Room queries and utilities
+  , roomIsVisited
   , roomIsLighted
+  , roomConnections
+  , roomRegion
+  , roomEnclosing
   , isVoid
   , updateFirstRoom
 
@@ -98,6 +135,12 @@ makeFieldLabelsNoPrefix ''RoomData
 makeFieldLabelsNoPrefix ''Connection
 
 -- | An `Object` with `RoomData`.
+-- | A room object with room-specific data and behaviour.
+--
+-- Wraps an `Object` (from `Yaifl.Object.Kind`) with `RoomData`, providing access to room properties
+-- such as connections, darkness, visitation state, and regional containment through the
+-- `HasField` instance. Maintains compatibility with the object system via
+-- `HasEntity` and `IsObject` instances.
 newtype Room wm = Room (Object wm (RoomData wm) (WMObjSpecifics wm))
   deriving newtype (Eq, Ord, Generic)
 
@@ -110,14 +153,18 @@ instance Display (Room wm) where
 instance HasEntity (Room wm) where
   getEntity (Room a) = objectId a
 
--- | A place where new `Yaifl.Model.Objects.Thing`s are placed by default, to avoid having locations be `Maybe`.
+-- | The Void room ID used as a default placement location.
+-- The Void (Entity -1) serves as a fallback to avoid `Maybe` locations
+-- when objects need a default container. Objects in The Void are not
+-- considered part of the active game world and may be removed at any time.
 voidID :: TaggedEntity RoomTag
 voidID = unsafeTagEntity $ Entity (-1)
 
 instance Taggable (Room wm) EnclosingTag
 instance Taggable (Room wm) RoomTag
 
--- | Tag a room entity.
+-- | Tag a room with its entity for type-safe references.
+-- Uses the room's object ID to create a tagged entity reference.
 tagRoomEntity ::
   Room wm
   -> TaggedEntity RoomTag
@@ -126,24 +173,47 @@ tagRoomEntity r = tagEntity r (r ^. #objectId)
 instance IsObject (Room wm) where
   isThing = const False
 
-isNotVisited ::
-  RoomData wm
+-- | Check if a room has been visited.
+roomIsVisited ::
+  Room wm
   -> Bool
-isNotVisited = (/= Visited) . isVisited
+roomIsVisited = (== Visited) . view (#objectData % #isVisited)
 
+-- | Check if a room is currently lighted.
 roomIsLighted ::
   Room wm
   -> Bool
 roomIsLighted = (== Lighted) . view (#objectData % #darkness)
 
+-- | Check if an object is the void ID (default placement location).
 isVoid ::
   HasEntity a
   => a
   -> Bool
 isVoid = (unTagEntity voidID ==) . getEntity
 
+-- | Update the first room in metadata to the given room.
+-- This sets the default starting location for the player.
 updateFirstRoom ::
   State Metadata :> es
   => Room wm
   -> Eff es ()
-updateFirstRoom e = #firstRoom .= tagRoomEntity e
+updateFirstRoom e = #firstRoom .= tagRoomEntity e
+
+-- | Get the connections from a room to other rooms.
+roomConnections ::
+  Room wm
+  -> MapConnections wm
+roomConnections = view (#objectData % #mapConnections)
+
+-- | Get the region containing a room.
+roomRegion ::
+  Room wm
+  -> ContainingRegion
+roomRegion = view (#objectData % #containingRegion)
+
+-- | Get the enclosing data for a room.
+roomEnclosing ::
+  Room wm
+  -> Enclosing
+roomEnclosing = view (#objectData % #enclosing)