comment cleanup

border/border.go

@@ -13,9 +13,9 @@ const (
 	// cellWidth represents how many columns are in a cell
 	cellWidth = 4
 
-	// marginLeft and marginTop represent how much to offset the
-	// chess board from the top left of the terminal to account for
-	// padding and rank labels
+	// marginLeft and marginTop represent the offset of the chess
+	// board from the top left of the terminal window. This is to
+	// account for padding and rank labels
 	marginLeft = 3
 	marginTop  = 1
 
@@ -23,8 +23,8 @@ const (
 	Horizontal = "─"
 )
 
-// Cell returns the square that was clicked based on mouse
-// coordinates adjusting for margins and cell dimensions.
+// Cell returns the square that was clicked based on mouse coordinates adjusted
+// for margins and cell dimensions.
 func Cell(x, y int) string {
 	col := (x - marginLeft) / cellWidth
 	row := board.LastRow - (y-marginTop)/cellHeight

fen/fen.go

@@ -5,12 +5,14 @@ import (
 	"strings"
 )
 
-// Tokens returns the tokens of a FEN string
+// Tokens returns the (6) tokens of a FEN string
+//
+// [Pieces, Turn, Castling, En passant, Halfmove Clock, Fullmove number]
 func Tokens(fen string) []string {
 	return strings.Split(fen, " ")
 }
 
-// Ranks returns a slice of ranks from the FEN string
+// Ranks returns a slice of ranks from the first token of a FEN string
 func Ranks(fen string) []string {
 	return strings.Split(Tokens(fen)[0], "/")
 }
@@ -35,12 +37,12 @@ func Grid(fen string) [8][8]string {
 	return grid
 }
 
-// isNumeric returns true if the current rune is a number
+// isNumeric returns whether a rune is a number
 func isNumeric(r rune) bool {
 	return r >= '0' && r <= '9'
 }
 
-// runeToInt converts a rune to an int
+// runeToInt converts a rune to an integer
 func runeToInt(r rune) int {
 	return int(r - '0')
 }

game/game.go

@@ -16,9 +16,10 @@ import (
 	. "github.com/maaslalani/gambit/style"
 )
 
-// model stores the state of the chess game. It tracks the board, legal moves,
-// and the selected piece as well as the subset of legal moves for the selected
-// piece.
+// model stores the state of the chess game.
+//
+// It tracks the board, legal moves, and the selected piece. It also keeps
+// track of the subset of legal moves for the currently selected piece
 type model struct {
 	board      *dt.Board
 	moves      []dt.Move
@@ -26,9 +27,9 @@ type model struct {
 	selected   string
 }
 
-// InitialModel returns an initial model of the game board using the starting
-// position of a normal chess game and generating the legal moves from the
-// starting position.
+// InitialModel returns an initial model of the game board. It uses the
+// starting position of a normal chess game and generates the legal moves from
+// the starting position.
 func InitialModel() tea.Model {
 	board := dt.ParseFen(dt.Startpos)
 	return model{
@@ -42,9 +43,11 @@ func (m model) Init() tea.Cmd {
 	return nil
 }
 
-// View converts a FEN string into a chess board with all pieces and empty
-// squares in a grid like pattern. We highlight the selected piece and the
-// legal moves for that piece so the user know where they can move.
+// View converts a FEN string into a human readable chess board. All pieces and
+// empty squares are arranged in a grid-like pattern. The selected piece is
+// highlighted and the legal moves for the selected piece are indicated by a
+// dot (.) for empty squares. Pieces that may be captured by the selected piece
+// are highlighted.
 //
 // For example, if the user selects the white pawn on E2 we indicate that they
 // can move to E3 and E4 legally.
@@ -72,6 +75,9 @@ func (m model) View() string {
 	var s strings.Builder
 	s.WriteString(border.Top())
 
+	// Traverse through the rows and columns of the board and print out the
+	// pieces and empty squares. Once a piece is selected, highlight the legal
+	// moves and pieces that may be captured by the selected piece.
 	for r, row := range fen.Grid(m.board.ToFen()) {
 		rr := board.LastRow - r
 		s.WriteString(Faint(fmt.Sprintf(" %d ", rr+1)) + border.Vertical)
@@ -79,10 +85,14 @@ func (m model) View() string {
 		for c, cell := range row {
 			display := pieces.Display[cell]
 
+			// The user selected the current cell, highlight it so they know it is
+			// selected.
 			if m.selected == position.ToSquare(rr, c) {
 				display = Cyan(display)
 			}
 
+			// Show all the cells to which the piece may move. If it is an empty cell
+			// we present a coloured dot, otherwise color the capturable piece.
 			if moves.IsLegal(m.pieceMoves, position.ToSquare(rr, c)) {
 				if cell == "" {
 					display = "."

moves/moves.go

@@ -6,8 +6,8 @@ import (
 	dt "github.com/dylhunn/dragontoothmg"
 )
 
-// IsLegal determines whether it is legal to move the the destination
-// square given a piece's legal moves
+// IsLegal determines whether it is legal to move to a destination square given
+// all of the legal moves that can be made by a piece.
 func IsLegal(legalMoves []dt.Move, destination string) bool {
 	for _, move := range legalMoves {
 		if strings.HasSuffix(move.String(), destination) {
@@ -17,12 +17,12 @@ func IsLegal(legalMoves []dt.Move, destination string) bool {
 	return false
 }
 
-// LegalSelected returns the legal moves for a given piece this is usually
-// for the selected piece so that we know to which we can move. If there is no
-// selected piece we return an empty array of moves.
+// LegalSelected returns the legal moves for a given piece based on an origin
+// square given all the current legal moves for all pieces on the board.
 func LegalSelected(moves []dt.Move, selected string) []dt.Move {
 	var legalMoves []dt.Move
 
+	// Return an empty slice if there is no square selected
 	if selected == "" {
 		return legalMoves
 	}

pieces/pieces.go

@@ -1,7 +1,7 @@
 package pieces
 
-// Display maps pieces in FEN representation to their ASCII
-// representation for the user.
+// Display maps pieces from their FEN representations to their ASCII
+// representations for a more human readable experience.
 var Display = map[string]string{
 	"":  " ",
 	"B": "♗",

position/position.go

@@ -7,7 +7,7 @@ import (
 	"github.com/maaslalani/gambit/board"
 )
 
-// colToFile returns the File given a column
+// colToFile returns the file given a column
 func colToFile(col int) string {
 	if col < board.FirstCol {
 		col = board.FirstCol
@@ -17,7 +17,7 @@ func colToFile(col int) string {
 	return fmt.Sprintf("%c", col+'a')
 }
 
-// rowToRank returns a Rank given a row
+// rowToRank returns a rank given a row
 func rowToRank(row int) int {
 	if row < board.FirstRow {
 		row = board.FirstRow
@@ -27,10 +27,8 @@ func rowToRank(row int) int {
 	return row + 1
 }
 
-// ToSquare returns the square position of a given row and
-// column for display or checking legal moves.
-//
-// For example, ToSquare(0, 0) returns a1.
+// ToSquare returns the square position (e.g. a1) of a given row and column
+// (e.g. 0,0) for display or checking legal moves.
 func ToSquare(row, col int) string {
 	return colToFile(col) + strconv.Itoa(rowToRank(row))
 }

square/square.go

@@ -6,7 +6,7 @@ import (
 	"github.com/maaslalani/gambit/board"
 )
 
-// fileToCol returns column number for a given file rune
+// fileToCol returns column number (e.g. 0) for a given file (e.g. 'a').
 func fileToCol(file rune) int {
 	col := int(file - 'a')
 	if col < board.FirstCol {
@@ -17,7 +17,7 @@ func fileToCol(file rune) int {
 	return col
 }
 
-// rankToRow returns a row number for a given rank
+// rankToRow returns a row number (e.g. 0) for a given rank (e.g. 1).
 func rankToRow(rank int) int {
 	row := rank - 1
 	if row < board.FirstRow {
@@ -28,11 +28,8 @@ func rankToRow(rank int) int {
 	return row
 }
 
-// ToPosition takes a square string and returns the
-// corresponding row and column for compatibility with the grid
-// (8x8 matrix).
-//
-// For example: "a1" returns (0, 0) and "h8" returns (7, 7).
+// ToPosition takes a square (e.g. a1) and returns the corresponding row and
+// column (e.g. 0,0) for compatibility with the grid (8x8 matrix).
 func ToPosition(square string) (int, int) {
 	col := fileToCol(rune(square[0]))
 	row, _ := strconv.Atoi(string(square[1]))