Make godoc happy, and add extra comments.

controller/types.go

@@ -1,18 +1,33 @@
 package controller
 
+// Simple interface to store values shared amongst packages.
 type Controller struct {
-	Blocks    []int
+	// All possible blocks/rows available
-	Row1      string
+	Blocks []int
-	Row2      string
+	// 1st row of the Sudoku puzzle.
-	Row3      string
+	Row1 string
-	Row4      string
+	// 2nd row of the Sudoku puzzle.
-	Row5      string
+	Row2 string
-	Row6      string
+	// 3rd row of the Sudoku puzzle.
-	Row7      string
+	Row3 string
-	Row8      string
+	// 4th row of the Sudoku puzzle.
-	Row9      string
+	Row4 string
+	// 5th row of the Sudoku puzzle.
+	Row5 string
+	// 6th row of the Sudoku puzzle.
+	Row6 string
+	// 7th row of the Sudoku puzzle.
+	Row7 string
+	// 8th row of the Sudoku puzzle.
+	Row8 string
+	// 9th row of the Sudoku puzzle.
+	Row9 string
+	// Slice with all found solutions.
 	Solutions []string
-	NumCPUs   int
+	// Number of CPUs Go routines are allowed to use.
-	Split     int
+	NumCPUs int
-	Part      int
+	// Number of parts the search should be split into.
+	Split int
+	// Which part of the search should the solver focus on.
+	Part int
 }

export/human-readable.go

@@ -5,6 +5,7 @@ import (
 	"log"
 )
 
+// Print solutions into a human friendly format for in the console.
 func (export *Export) PrintSolutions() {
 	for solutionIndex, solution := range export.Controller.Solutions {
 		log.Printf("\nSolution #%d:", solutionIndex+1)

export/types.go

@@ -2,6 +2,7 @@ package export
 
 import "gitea.ligthert.net/golang/sudoku-funpark/controller"
 
+// A simple inteface to export found solutions in different formats.
 type Export struct {
 	Controller *controller.Controller
 }

flags/parse.go

@@ -8,6 +8,7 @@ import (
 	"runtime"
 )
 
+// Parse command-line parameters, test input, store them in the Controller.
 func (flags *Flags) ParseFlags() {
 
 	// Define parameters
@@ -73,6 +74,11 @@ func (flags *Flags) ParseFlags() {
 
 }
 
+// Validate if a row is properly set.
+// This check for:
+// - Correct length
+// - Correct numbers
+// - Numbers only present once
 func (flags *Flags) validateRow(name string, row string) {
 
 	var found bool
@@ -116,6 +122,7 @@ func (flags *Flags) validateRow(name string, row string) {
 
 }
 
+// Validate if the char provided is 0-9
 func (flags *Flags) validChar(char rune) (valid bool) {
 	decvals := [10]int{48, 49, 50, 51, 52, 53, 54, 55, 56, 57}
 
@@ -128,6 +135,7 @@ func (flags *Flags) validChar(char rune) (valid bool) {
 	return
 }
 
+// Print help information for the end-user
 func (flags *Flags) printUsage() {
 	fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n", os.Args[0])
 	fmt.Fprintf(flag.CommandLine.Output(), "\nPut every row of a Sudoku puzzle as paramters.\nUse '0' for what is currently blank in the puzzle you wish to solve.\n\n")

flags/types.go

@@ -2,6 +2,7 @@ package flags
 
 import "gitea.ligthert.net/golang/sudoku-funpark/controller"
 
+// Interface to parse command-line parameters
 type Flags struct {
 	Controller *controller.Controller
 }

solver/blocks.go

@@ -13,6 +13,7 @@ import (
 //go:embed blocks.csv
 var f embed.FS
 
+// Load all possible blocks from CSV in to memory
 func (solver *Solver) LoadBlocks() {
 
 	defer solver.timeTrack(time.Now(), "Loaded blocks")

solver/processing.go

@@ -6,6 +6,7 @@ import (
 	"time"
 )
 
+// Find all possible blocks that can be used to find a solution.
 func (solver *Solver) PopulateBlocks() {
 
 	defer solver.timeTrack(time.Now(), "Populated blocks")
@@ -26,6 +27,7 @@ func (solver *Solver) PopulateBlocks() {
 
 }
 
+// The actual function that finds the blocks matching the partial blocks.
 func (solver *Solver) findBlocks(row *string, rows *[]int) {
 	// Declare selection
 	var selection []int
@@ -61,6 +63,7 @@ func (solver *Solver) findBlocks(row *string, rows *[]int) {
 	*rows = selection
 }
 
+// Iterate through all combination of blocks and validate them.
 func (solver *Solver) CheckCombinations() {
 	for rows1Index := range solver.row1s {
 		for rows2Index := range solver.row2s {
@@ -83,6 +86,7 @@ func (solver *Solver) CheckCombinations() {
 	}
 }
 
+// Validate the provided rows and verify it is a valid solution.
 func (solver *Solver) validator(rows1Index int, rows2Index int, rows3Index int, rows4Index int, rows5Index int, rows6Index int, rows7Index int, rows8Index int, rows9Index int) {
 
 	solver.counter.Add(1)
@@ -93,6 +97,8 @@ func (solver *Solver) validator(rows1Index int, rows2Index int, rows3Index int,
 
 }
 
+// Keep track and output progress.
+// Calculate rates, display percentages, estimate the ETA till completion.
 func (solver *Solver) Tracker() {
 
 	// Add time tracking
@@ -187,6 +193,7 @@ func (solver *Solver) Tracker() {
 
 }
 
+// Validate combination
 func (solver *Solver) validateCombination(row1 int, row2 int, row3 int, row4 int, row5 int, row6 int, row7 int, row8 int, row9 int) (retval bool) {
 	retval = true
 
@@ -242,6 +249,7 @@ func (solver *Solver) validateCombination(row1 int, row2 int, row3 int, row4 int
 	return retval
 }
 
+// Calculate the average rate in a stored slice of rates.
 func (solver *Solver) calcAVG() (avg int64) {
 	var avgSum int64
 

solver/split.go

@@ -7,9 +7,9 @@ import (
 	"time"
 )
 
-// Perform some checks
+// Renders workload for an agent.
-// and
+// Checks if this feature can be used, otherwise exits.
-// Modify solver.row1s so it limits the workload to what is only desired.
+// Modify solver.row1s so it limits the workload to what is only desired
 func (solver *Solver) SelectWorkload() {
 	if solver.Controller.Split > len(solver.row1s) {
 		log.Println("ERROR: Unable to divide the workload in " + strconv.Itoa(solver.Controller.Split) + " parts, when only " + strconv.Itoa(len(solver.row1s)) + " are available.\n\n")

solver/stash.go

@@ -4,6 +4,7 @@ import (
 	"strconv"
 )
 
+// Prepare a valid solution for storage.
 func (solver *Solver) renderCombination(row1 int, row2 int, row3 int, row4 int, row5 int, row6 int, row7 int, row8 int, row9 int) string {
 
 	row1s := strconv.Itoa(row1)

solver/timers.go

@@ -5,6 +5,8 @@ import (
 	"time"
 )
 
+// A simple function to track time
+// Use with `defer`
 func (solver *Solver) timeTrack(start time.Time, msg string) {
 	elapsed := time.Since(start)
 	log.Printf("%s (%s)", msg, elapsed)

solver/types.go

@@ -6,7 +6,7 @@ import (
 	"gitea.ligthert.net/golang/sudoku-funpark/controller"
 )
 
-// Struct/Interface containing all the important variabes it functions need access to.
+// Solve a given Sudoku puzzle by iterating through all possible solutions.
 type Solver struct {
 	Controller *controller.Controller
 	row1s      []int