From 6dd5d2f232291de17131b51b3848057b870a4270 Mon Sep 17 00:00:00 2001 From: Sacha Ligthert Date: Tue, 28 Jan 2025 00:31:02 +0100 Subject: [PATCH] Make godoc happy, and add extra comments. --- controller/types.go | 41 +++++++++++++++++++++++++++------------- export/human-readable.go | 1 + export/types.go | 1 + flags/parse.go | 8 ++++++++ flags/types.go | 1 + solver/blocks.go | 1 + solver/processing.go | 8 ++++++++ solver/split.go | 6 +++--- solver/stash.go | 1 + solver/timers.go | 2 ++ solver/types.go | 2 +- 11 files changed, 55 insertions(+), 17 deletions(-) diff --git a/controller/types.go b/controller/types.go index bca66c2..af9e509 100644 --- a/controller/types.go +++ b/controller/types.go @@ -1,18 +1,33 @@ package controller +// Simple interface to store values shared amongst packages. type Controller struct { - Blocks []int - Row1 string - Row2 string - Row3 string - Row4 string - Row5 string - Row6 string - Row7 string - Row8 string - Row9 string + // All possible blocks/rows available + Blocks []int + // 1st row of the Sudoku puzzle. + Row1 string + // 2nd row of the Sudoku puzzle. + Row2 string + // 3rd row of the Sudoku puzzle. + Row3 string + // 4th row of the Sudoku puzzle. + 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 - Split int - Part int + // Number of CPUs Go routines are allowed to use. + NumCPUs int + // Number of parts the search should be split into. + Split int + // Which part of the search should the solver focus on. + Part int } diff --git a/export/human-readable.go b/export/human-readable.go index 01eb6e6..3f4ac0f 100644 --- a/export/human-readable.go +++ b/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) diff --git a/export/types.go b/export/types.go index 82d7e2d..c054e59 100644 --- a/export/types.go +++ b/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 } diff --git a/flags/parse.go b/flags/parse.go index d029d90..d5e38e2 100644 --- a/flags/parse.go +++ b/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") diff --git a/flags/types.go b/flags/types.go index 439a4dc..e636832 100644 --- a/flags/types.go +++ b/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 } diff --git a/solver/blocks.go b/solver/blocks.go index 2bfd2ae..c639f8f 100644 --- a/solver/blocks.go +++ b/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") diff --git a/solver/processing.go b/solver/processing.go index 9f1b0b5..b5389d3 100644 --- a/solver/processing.go +++ b/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 diff --git a/solver/split.go b/solver/split.go index 0f59bbb..d501d92 100644 --- a/solver/split.go +++ b/solver/split.go @@ -7,9 +7,9 @@ import ( "time" ) -// Perform some checks -// and -// Modify solver.row1s so it limits the workload to what is only desired. +// Renders workload for an agent. +// Checks if this feature can be used, otherwise exits. +// 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") diff --git a/solver/stash.go b/solver/stash.go index 8174fb5..d3f9b34 100644 --- a/solver/stash.go +++ b/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) diff --git a/solver/timers.go b/solver/timers.go index 6ed2952..bc77f7e 100644 --- a/solver/timers.go +++ b/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) diff --git a/solver/types.go b/solver/types.go index 46dacfa..00641de 100644 --- a/solver/types.go +++ b/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