From 43a4f9b48399f8a8de78a8124928614e5ca119df Mon Sep 17 00:00:00 2001
From: decentral1se <cellarspoon@riseup.net>
Date: Wed, 10 May 2023 18:34:09 +0200
Subject: [PATCH] docs: docstrings

---
 gshmm.go | 34 ++++++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/gshmm.go b/gshmm.go
index a836d7c..103f3c3 100644
--- a/gshmm.go
+++ b/gshmm.go
@@ -1,3 +1,4 @@
+// go-sh-manymanuals TODO
 package main
 
 import (
@@ -15,6 +16,7 @@ import (
 	"github.com/sahilm/fuzzy"
 )
 
+// help is the command-line interface help output.
 const help = `go-sh-manymanuals: TODO
 
 TODO
@@ -27,13 +29,20 @@ Options:
 // required before the filtering logic commences actually filtering.
 const minCharsUntilFilter = 2
 
+// helpFlag is the help flag for the command-line interface.
 var helpFlag bool
 
+// handleCliFlags handles command-line flags.
 func handleCliFlags() {
 	flag.BoolVar(&helpFlag, "h", false, "output help")
 	flag.Parse()
 }
 
+// readPDF reads the plain text contents of a PDF. This does not include the
+// formatting. Only the content you see when you view it through a PDF reader.
+// The library we're using makes use of the C bindings to the Poppler PDF
+// library https://poppler.freedesktop.org which appears to offer a good mix of
+// reliability and effectiveness.
 func readPDF(name string) (string, error) {
 	doc, err := pdf.Open(name)
 	if err != nil {
@@ -49,15 +58,17 @@ func readPDF(name string) (string, error) {
 	return txt, nil
 }
 
+// model offers the core of the state for the entire UI.
 type model struct {
-	filterInput       textinput.Model // fuzzy search interface
-	datasheets        []datasheet     // all datasheets under cwd
-	dataSheetsView    []string        // filtered view on all datasheets
-	dataSheetViewport viewport.Model
+	filterInput       textinput.Model // Fuzzy search interface
+	datasheets        []datasheet     // All datasheets under cwd
+	dataSheetsView    []string        // Filtered view on all datasheets
+	dataSheetViewport viewport.Model  // Viewport for the PDF content
 }
 
-// TODO: cache this somewhere, it's called several times... in the model?
+// dataSheetNames lists all datasheet names.
 func (m model) dataSheetNames() []string {
+	// TODO: cache this somewhere, it's called several times... in the model?
 	var names []string
 	for _, datasheet := range m.datasheets {
 		names = append(names, datasheet.filename)
@@ -65,6 +76,7 @@ func (m model) dataSheetNames() []string {
 	return names
 }
 
+// datasheetFromName retrieves a datasheet via a name.
 func (m model) datasheetFromName(name string) string {
 	for _, d := range m.datasheets {
 		if d.filename == name {
@@ -74,12 +86,14 @@ func (m model) datasheetFromName(name string) string {
 	return ""
 }
 
+// datasheet represents a datasheet on disk.
 type datasheet struct {
-	filename string
-	absPath  string
-	contents string
+	filename string // The name of the file
+	absPath  string // the absolute file path
+	contents string // the contents of the PDF
 }
 
+// initialModel constucts an initial state for the UI.
 func initialModel() model {
 	input := textinput.New()
 	input.Focus()
@@ -123,10 +137,12 @@ func initialModel() model {
 	return m
 }
 
+// Init initialises the program.
 func (m model) Init() tea.Cmd {
 	return textinput.Blink
 }
 
+// Update updates the program state.
 func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	var (
 		cmd  tea.Cmd
@@ -178,6 +194,7 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	return m, tea.Batch(cmds...)
 }
 
+// View outputs the program state for viewing.
 func (m model) View() string {
 	body := strings.Builder{}
 
@@ -194,6 +211,7 @@ func (m model) View() string {
 	return body.String()
 }
 
+// main is the command-line entrypoint.
 func main() {
 	handleCliFlags()