short module descriptions (#1690)

Towards #1689

The [`Description:` field](https://haskell-haddock.readthedocs.io/en/latest/markup.html#the-module-description) in a module's toplevel haddock will be displayed on the Contents page.

![Screenshot from 2023-12-14 20-55-26](https://github.com/swarm-game/swarm/assets/261693/841f2834-8273-4394-b764-8f5f4479b9c4)

src/Swarm/App.hs

@@ -3,6 +3,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Application entry point
 --
 -- Main entry point for the Swarm application.
 module Swarm.App where

src/Swarm/Constant.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Constants used throughout the UI and game
 --
 -- Constants used throughout the UI and game.
 module Swarm.Constant where

src/Swarm/Doc/Keyword.hs

@@ -3,6 +3,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: keywords for doc gen and testing
 --
 -- Collect keywords for documentation generation and testing.
 module Swarm.Doc.Keyword (

src/Swarm/Doc/Pedagogy.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Pedagogical soundness of tutorials
 --
 -- Assess pedagogical soundness of the tutorials.
 --

src/Swarm/Doc/Util.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Doc markup utilities
 --
 -- Utilities for generating doc markup
 module Swarm.Doc.Util where

src/Swarm/Effect.hs

@@ -1,3 +1,6 @@
+-- |
+-- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Effect system
 module Swarm.Effect (
   module X,
 )

src/Swarm/Effect/Time.hs

@@ -4,6 +4,9 @@
 {-# LANGUAGE KindSignatures #-}
 {-# LANGUAGE UndecidableInstances #-}
 
+-- |
+-- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Time effects
 module Swarm.Effect.Time where
 
 import Control.Algebra

src/Swarm/Game/Achievement/Attainment.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Achievements player obtained
 --
 -- Metadata about achievements that the player has obtained.
 module Swarm.Game.Achievement.Attainment (

src/Swarm/Game/Achievement/Definitions.hs

@@ -1,5 +1,6 @@
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: All achievements enumerated
 --
 -- Definitions of all possible achievements.
 module Swarm.Game.Achievement.Definitions (

src/Swarm/Game/Achievement/Description.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Flavor text
 --
 -- Flavor text about all defined achievements.
 module Swarm.Game.Achievement.Description where

src/Swarm/Game/Achievement/Persistence.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Achievements load/save
 --
 -- Load/save logic for achievements.
 -- Each achievement is saved to its own file to better

src/Swarm/Game/CESK.hs

@@ -4,6 +4,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: State machine of Swarm's interpreter
 --
 -- The Swarm interpreter uses a technique known as a
 -- <https://matt.might.net/articles/cesk-machines/ CESK machine> (if

src/Swarm/Game/Display.hs

@@ -6,6 +6,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: TUI rendering of entities
 --
 -- Utilities for describing how to display in-game entities in the TUI.
 module Swarm.Game.Display (

src/Swarm/Game/Entity.hs

@@ -3,6 +3,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Object that exists in the world
 --
 -- An 'Entity' represents an object that exists in the world.  Each
 -- entity has a way to be displayed, some metadata such as a name and

src/Swarm/Game/Location.hs

@@ -5,6 +5,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Locations and headings
 --
 -- Locations and headings.
 module Swarm.Game.Location (

src/Swarm/Game/Recipe.hs

@@ -3,6 +3,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Entity transformations, not limited to "crafting"
 --
 -- A recipe represents some kind of process for transforming
 -- some input entities into some output entities.

src/Swarm/Game/ResourceLoading.hs

@@ -2,6 +2,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Fetching game data
 --
 -- Various utilities related to loading game data files.
 module Swarm.Game.ResourceLoading where

src/Swarm/Game/Scenario.hs

@@ -7,6 +7,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Standalone worlds
 --
 -- Scenarios are standalone worlds with specific starting and winning
 -- conditions, which can be used both for building interactive

src/Swarm/Game/Scenario/Objective.hs

@@ -4,6 +4,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Goals of scenario
 module Swarm.Game.Scenario.Objective where
 
 import Control.Applicative ((<|>))

src/Swarm/Game/State.hs

@@ -5,6 +5,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Game-related state and utilities
 --
 -- Definition of the record holding all the game-related state, and various related
 -- utility functions.

src/Swarm/Game/Step.hs

@@ -5,11 +5,12 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Stepping robot CESK machines
 --
 -- Facilities for stepping the robot CESK machines, /i.e./ the actual
 -- interpreter for the Swarm language.
 --
--- ** Note on the IO:
+-- == Note on the IO:
 --
 -- The only reason we need @IO@ is so that robots can run programs
 -- loaded from files, via the 'Swarm.Language.Syntax.Run' command.

src/Swarm/Game/Step/Const.hs

@@ -6,6 +6,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Robot command logic
 --
 -- Implementation of robot commands
 module Swarm.Game.Step.Const where

src/Swarm/Game/World.hs

@@ -5,6 +5,7 @@
 
 -- |
 -- SPDX-License-Identifier: BSD-3-Clause
+-- Description: Grid on which the game takes place
 --
 -- A /world/ refers to the grid on which the game takes place, and the
 -- things in it (besides robots). A world has a base, immutable