From e4f38fcde02d22b780886a43971aab9ba1d07fe9 Mon Sep 17 00:00:00 2001
From: Dave Smith <davesmith.00000@gmail.com>
Date: Tue, 14 Nov 2023 22:13:00 +0000
Subject: [PATCH] Fixed #25: All top level types have headline docs

---
 .../indigoengine/roguelike/starterkit/terminal/MapTile.scala  | 3 +++
 .../roguelike/starterkit/terminal/TerminalClones.scala        | 3 +++
 .../io/indigoengine/roguelike/starterkit/utils/FOV.scala      | 4 ++++
 .../indigoengine/roguelike/starterkit/utils/PathFinder.scala  | 4 ++++
 4 files changed, 14 insertions(+)

diff --git a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/MapTile.scala b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/MapTile.scala
index 4350ba03..f496ab2a 100644
--- a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/MapTile.scala
+++ b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/MapTile.scala
@@ -5,6 +5,9 @@ import indigo.*
 import indigo.shared.datatypes.RGBA
 import io.indigoengine.roguelike.starterkit.Tile
 
+/** Represents the three basic properties of a tile: Character, foreground colour, and background
+  * colour.
+  */
 final case class MapTile(char: Tile, foreground: RGBA, background: RGBA):
   def withChar(newChar: Tile): MapTile =
     this.copy(char = newChar)
diff --git a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/TerminalClones.scala b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/TerminalClones.scala
index 9f2cf9be..ab993d6b 100644
--- a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/TerminalClones.scala
+++ b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/terminal/TerminalClones.scala
@@ -5,6 +5,9 @@ import io.indigoengine.roguelike.starterkit.Tile
 
 import scala.annotation.tailrec
 
+/** Represents the output of converting a Terminal into clones ready for rendering. You must add the
+  * clones to you scene and register the clone blanks.
+  */
 final case class TerminalClones(blanks: Batch[CloneBlank], clones: Batch[CloneTiles]):
   def |+|(other: TerminalClones): TerminalClones =
     combine(other)
diff --git a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/FOV.scala b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/FOV.scala
index 50b71904..8c52ed10 100644
--- a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/FOV.scala
+++ b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/FOV.scala
@@ -4,8 +4,12 @@ import indigo.*
 
 import scala.annotation.tailrec
 
+/** Helper methods for working out a players field of view. */
 object FOV:
 
+  /** An implementation of the Bresenham Line algorithm, which plots clean lines across grids. Used
+    * by drawing tools and in this case, for lines of sight.
+    */
   @SuppressWarnings(Array("scalafix:DisableSyntax.var"))
   def bresenhamLine(from: Point, to: Point): Batch[Point] =
     val x0: Int = from.x
diff --git a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/PathFinder.scala b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/PathFinder.scala
index 8266bf0f..9b4c475f 100644
--- a/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/PathFinder.scala
+++ b/roguelike-starterkit/src/main/scala/io/indigoengine/roguelike/starterkit/utils/PathFinder.scala
@@ -7,6 +7,7 @@ import indigo.shared.dice.Dice
 
 import scala.annotation.tailrec
 
+/** A simple path finding implementation for a grid. */
 final case class PathFinder(size: Size, grid: Batch[GridSquare]):
 
   def contains(coords: Point): Boolean =
@@ -25,6 +26,7 @@ final case class PathFinder(size: Size, grid: Batch[GridSquare]):
       this.copy(grid = PathFinder.scoreGridSquares(start: Point, end: Point, this, scoreAmount))
     )
 
+/** A simple path finding implementation for a grid. */
 object PathFinder:
 
   def sampleAt(searchGrid: PathFinder, coords: Point, gridWidth: Int): Batch[GridSquare] =
@@ -143,6 +145,7 @@ object PathFinder:
     )
   }
 
+/** A GridSquare represents a position on the gird in the PathFinder implementation. */
 enum GridSquare(val score: Int):
   val index: Int
   val coords: Point
@@ -155,6 +158,7 @@ enum GridSquare(val score: Int):
       case gs: Walkable => gs.copy(weight = newScore)
       case gs: Blocked  => gs
 
+/** A GridSquare represents a position on the gird in the PathFinder implementation. */
 object GridSquare:
   val Max: Int = Int.MaxValue