docs

8 files changed, 45 insertions, 7 deletions

diff --git a/model/indexer.go b/model/indexer.go
index e82e3af..71281aa 100644
--- a/model/indexer.go
+++ b/model/indexer.go
@@ -4,6 +4,8 @@ import (
 	"io/fs"
 )
 
+// Indexer is used to create targets from pik-enabled sources
+// these have to be listed in main.go
 type Indexer interface {
 	Index(path string, fs fs.FS, runners []Runner) ([]Target, error)
 }
diff --git a/model/init.go b/model/init.go
index 13158da..e5dfa9b 100644
--- a/model/init.go
+++ b/model/init.go
@@ -1,5 +1,7 @@
 package model
 
+// Initializer has setup to do before pik can start
+// these have to be registered in main.go
 type Initializer interface {
 	Init() error
 }
diff --git a/model/mod.go b/model/mod.go
index 0a680b5..3f83bed 100644
--- a/model/mod.go
+++ b/model/mod.go
@@ -1,5 +1,8 @@
 package model
 
+// Modder can change sources after their creation
+// this can add additional data, customization, etc.
+// these have to be registered in main.go
 type Modder interface {
 	Mod(source *Source, result *HydratedSource) error
 }
diff --git a/model/runner.go b/model/runner.go
index b413d51..e8cbcc0 100644
--- a/model/runner.go
+++ b/model/runner.go
@@ -4,6 +4,9 @@ import (
 	"io/fs"
 )
 
+// Runner knows how to go from a file to an exec.Cmd
+// these are mostly used for pikdex but other runners can use them as well
+// these have to be registered in main.go
 type Runner interface {
 	Hydrate(target Target) (HydratedTarget, error)
 	Wants(fs fs.FS, file string, entry fs.DirEntry) (bool, error)
diff --git a/model/source.go b/model/source.go
index 29cff05..b7f28d4 100644
--- a/model/source.go
+++ b/model/source.go
@@ -6,6 +6,8 @@ import (
 	"pik/spool"
 )
 
+// Source is a location containing stuff we can run
+// these get created when we find a makefile, .pik folder, etc.
 type Source struct {
 	identity.Identity
 	Tags
@@ -13,6 +15,9 @@ type Source struct {
 	Targets []Target
 }
 
+// HydratedSource is a Source with additional hydration
+// for the menu.
+// these do not get created unless we show the menu
 type HydratedSource struct {
 	*Source
 	HydratedTargets []HydratedTarget
diff --git a/model/state.go b/model/state.go
index 3ba2045..259684a 100644
--- a/model/state.go
+++ b/model/state.go
@@ -1,10 +1,14 @@
 package model
 
+// State is the complete collection of sources and their targets
 type State struct {
 	Sources []*Source
-	All     bool
+	// All contains whether --all was enabled during creation
+	All bool
 }
 
+// HydratedState is an extension of the State which contains
+// additional information which we use to display the menu
 type HydratedState struct {
 	*State
 	HydratedSources []*HydratedSource
diff --git a/model/tags.go b/model/tags.go
index 08cb135..a34f555 100644
--- a/model/tags.go
+++ b/model/tags.go
@@ -5,9 +5,11 @@ import (
 	"strings"
 )
 
+// Tag is some text which is contained in a filename which triggers pik functionality
 type Tag *string
 type TagAction func(src *Source)
 
+// New creates a new tag and registers it in the subsystems
 func New(input string) Tag {
 	result := &input
 	TagMap[input] = result
@@ -16,12 +18,19 @@ func New(input string) Tag {
 }
 
 var (
-	Here     = New("here")
-	Pre      = New("pre")
-	Post     = New("post")
-	Final    = New("final")
-	Hidden   = New("hidden")
-	Single   = New("single")
+	// Here will force the target to run in the current directory instead of the source directory
+	Here = New("here")
+	// Pre turns the target into a trigger, causing it to be triggered before another target gets ran
+	Pre = New("pre")
+	// Post turns the target into a trigger, causing it to be triggered after another target gets ran and exits succesfully
+	Post = New("post")
+	// Final turns the target into a trigger, causing it to be triggered after another target gets ran
+	Final = New("final")
+	// Hidden means the target is not visible in the menu
+	Hidden = New("hidden")
+	// Single means this target will not use any triggers
+	Single = New("single")
+	// Override means this should be selected instead of a non-override target, if possible
 	Override = New("override")
 )
 
diff --git a/model/target.go b/model/target.go
index b503381..683ab8f 100644
--- a/model/target.go
+++ b/model/target.go
@@ -4,21 +4,31 @@ import (
 	"os/exec"
 )
 
+// Target is something we want to run
 type Target interface {
 	Matches
+	// Create creates the exec.Cmd from itself. The model.Source this target is in is also available.
 	Create(s *Source) *exec.Cmd
 	Sub() []string
+	// Label will be used for its label in the menu
 	Label() string
 	Hydrate(src *Source) (HydratedTarget, error)
 	Tags() Tags
+	// ShortestId returns a short version of its identity
 	ShortestId() string
+	// Visible should return whether this target can be seen in the menu
 	Visible() bool
+	// Invocation should return the "canonical invocation": simple to remember
 	Invocation(src *Source) []string
 }
 
+// HydratedTarget is something we want to show in the menu
 type HydratedTarget interface {
 	Target
+	// Icon is some text which will be used as an icon
 	Icon() string
+	// Description is a one-line description of what this does
 	Description() string
+	// Target returns our inner target
 	Target() Target
 }