{doc} Add some code documentation

actr/buffer/buffer.go

@@ -1,3 +1,4 @@
+// Package buffer implements ACT-R buffers.
 package buffer
 
 import (

actr/modules/declarative_memory.go

@@ -93,6 +93,7 @@ type DeclarativeMemory struct {
 	MismatchPenalty *float64
 }
 
+// NewDeclarativeMemory creates and returns a new DeclarativeMemory module
 func NewDeclarativeMemory() *DeclarativeMemory {
 	decay := NewParamFloat(
 		"decay",
@@ -176,6 +177,7 @@ func (d DeclarativeMemory) BufferName() string {
 	return d.Buffers().At(0).BufferName()
 }
 
+// SetParam is called to set our module's parameter from the parameter in the code ("param")
 func (d *DeclarativeMemory) SetParam(param *params.Param) (err error) {
 	err = d.ValidateParam(param)
 	if err != nil {

actr/modules/extra_buffers.go

@@ -10,6 +10,7 @@ type ExtraBuffers struct {
 	Module
 }
 
+// NewExtraBuffers creates and returns a new ExtraBuffers module
 func NewExtraBuffers() *ExtraBuffers {
 	return &ExtraBuffers{
 		Module: Module{
@@ -20,6 +21,7 @@ func NewExtraBuffers() *ExtraBuffers {
 	}
 }
 
+// SetParam is called to set our module's parameter from the parameter in the code ("param")
 func (eb *ExtraBuffers) SetParam(param *params.Param) (err error) {
 	newBuffer := buffer.Buffer{
 		Name:         param.Key,

actr/modules/goal.go

@@ -16,6 +16,7 @@ type Goal struct {
 	SpreadingActivation *float64
 }
 
+// NewGoal creates and returns a new Goal module
 func NewGoal() *Goal {
 	spreadingActivation := NewParamFloat(
 		"spreading_activation",
@@ -38,6 +39,7 @@ func NewGoal() *Goal {
 	}
 }
 
+// SetParam is called to set our module's parameter from the parameter in the code ("param")
 func (g *Goal) SetParam(param *params.Param) (err error) {
 	err = g.ValidateParam(param)
 	if err != nil {

actr/modules/imaginal.go

@@ -16,6 +16,7 @@ type Imaginal struct {
 	Delay *float64
 }
 
+// NewImaginal creates and returns a new Imaginal module
 func NewImaginal() *Imaginal {
 	delay := NewParamFloat(
 		"delay",
@@ -38,6 +39,7 @@ func NewImaginal() *Imaginal {
 	}
 }
 
+// SetParam is called to set our module's parameter from the parameter in the code ("param")
 func (i *Imaginal) SetParam(param *params.Param) (err error) {
 	err = i.ValidateParam(param)
 	if err != nil {

actr/modules/modules.go

@@ -1,4 +1,4 @@
-// Package modules implements several ACT-R modules.
+// Package modules implements a module interface and several built-in ACT-R modules.
 package modules
 
 import (
@@ -17,9 +17,9 @@ type Module struct {
 	Version     string
 	Description string
 
-	BufferList buffer.List
+	BufferList buffer.List // The buffers this module provides (may be empty)
 
-	Params ParamInfoMap
+	Params ParamInfoMap // Parameters accepted by this module (may be empty)
 }
 
 // ModuleInterface provides an interface for the ACT-R concept of a "module".
@@ -63,6 +63,7 @@ func (m Module) HasParameters() bool {
 	return len(m.Params) > 0
 }
 
+// ParameterInfo returns the detailed info about a specific parameter given by "name"
 func (m Module) ParameterInfo(name string) ParamInterface {
 	info, ok := m.Params[name]
 	if ok {

actr/modules/params.go

@@ -1,28 +1,34 @@
 package modules
 
+// Ptr simply returns a pointer to a literal. e.g. Ptr(0.5)
+// This is useful when passing literals to functions which require pointers to basic types.
 func Ptr[T any](v T) *T {
 	return &v
 }
 
+// ParamInfo is the basic info about a parameter
 type ParamInfo struct {
 	Name        string
 	Description string
 }
 
+// ParamInt is an int parameter with optional min and max constraints
 type ParamInt struct {
 	ParamInfo
 
 	Min *int
 	Max *int
 }
 
+// ParamFloat is a float parameter with optional min and max constraints
 type ParamFloat struct {
 	ParamInfo
 
 	Min *float64
 	Max *float64
 }
 
+// ParamInterface provides an interface to a parameter
 type ParamInterface interface {
 	GetName() string
 	GetDescription() string
@@ -31,6 +37,7 @@ type ParamInterface interface {
 	GetMax() *float64
 }
 
+// ParamInfoMap maps a name to the parameter's info
 type ParamInfoMap map[string]ParamInterface
 
 func (p ParamInfo) GetName() string {
@@ -60,13 +67,15 @@ func (p ParamInt) GetMax() *float64 {
 func (p ParamFloat) GetMin() *float64 { return p.Min }
 func (p ParamFloat) GetMax() *float64 { return p.Max }
 
+// NewParamInt creates a new int param with optional min/max constraints
 func NewParamInt(name, description string, min, max *int) ParamInt {
 	return ParamInt{
 		ParamInfo{name, description},
 		min, max,
 	}
 }
 
+// NewParamFloat creates a new float param with optional min/max constraints
 func NewParamFloat(name, description string, min, max *float64) ParamFloat {
 	return ParamFloat{
 		ParamInfo{name, description},

actr/modules/procedural.go

@@ -14,6 +14,7 @@ type Procedural struct {
 	DefaultActionTime *float64
 }
 
+// NewProcedural creates and returns a new Procedural module
 func NewProcedural() *Procedural {
 	defActionTime := NewParamFloat(
 		"default_action_time",
@@ -33,6 +34,7 @@ func NewProcedural() *Procedural {
 	}
 }
 
+// SetParam is called to set our module's parameter from the parameter in the code ("param")
 func (p *Procedural) SetParam(param *params.Param) (err error) {
 	err = p.ValidateParam(param)
 	if err != nil {

actr/params/params.go

@@ -1,3 +1,4 @@
+// Package params implements parsed parameter information.
 package params
 
 import (
@@ -17,6 +18,7 @@ type Value struct {
 	Field  *Param
 }
 
+// Param is the key/value of a parameter from the parsed amod code.
 type Param struct {
 	Key   string
 	Value Value

amod/amod.go

@@ -1,3 +1,4 @@
+// Package amod implements parsing of amod files into actr.Models.
 package amod
 
 import (

cmd/root.go

@@ -1,3 +1,4 @@
+// Package cmd implements our command-line commands for working with gactar.
 package cmd
 
 import (

examples/embed.go

@@ -1,3 +1,5 @@
+// Package examples works around the problem of embedding relative paths and
+// is used to embed the examples.
 package examples
 
 import (

framework/framework.go

@@ -1,3 +1,4 @@
+// Package framework implements the abstract framework used by the concrete implementations.
 package framework
 
 import (

util/container/container.go

@@ -1,3 +1,4 @@
+// Package container implements some routines for working with slices.
 package container
 
 import (

util/decompress/decompress.go

@@ -1,3 +1,4 @@
+// Package decompress implements routines for unzipping and "untarring".
 package decompress
 
 import (
@@ -20,6 +21,7 @@ func (e ErrZipInvalidFilePath) Error() string {
 	return fmt.Sprintf("invalid file path: %q", e.FilePath)
 }
 
+// Untar a file to a target directory.
 func UntarFile(filePath, targetDir string) error {
 	file, err := os.Open(filePath)
 	if err != nil {
@@ -30,6 +32,7 @@ func UntarFile(filePath, targetDir string) error {
 	return Untar(file, targetDir)
 }
 
+// Untar a reader to a target directory.
 func Untar(reader io.Reader, targetDir string) error {
 	gzr, err := gzip.NewReader(reader)
 	if err != nil {
@@ -87,6 +90,7 @@ func Untar(reader io.Reader, targetDir string) error {
 	}
 }
 
+// Unzip a file to a target directory.
 func Unzip(filePath, targetDir string) (err error) {
 	archive, err := zip.OpenReader(filePath)
 	if err != nil {

util/executil/executil.go

@@ -1,3 +1,4 @@
+// Package executil implements a function for executing a command line.
 package executil
 
 import (

util/filesystem/filesystem.go

@@ -1,3 +1,5 @@
+// Package filesystem implements some functions and error handling for working
+// with files and directories.
 package filesystem
 
 import (
@@ -35,11 +37,13 @@ func (e ErrExeNotFound) Error() string {
 	return fmt.Sprintf("cannot find %q in your path:\n%q", e.ExeName, e.Path)
 }
 
+// DirExists returns true if the given path exists and is a directory.
 func DirExists(path string) bool {
 	stat, err := os.Stat(path)
 	return !os.IsNotExist(err) && stat.IsDir()
 }
 
+// CreateDir creates a directory if it does not exist.
 func CreateDir(path string) (err error) {
 	err = os.MkdirAll(path, 0750)
 	if err != nil && !os.IsExist(err) {
@@ -49,6 +53,7 @@ func CreateDir(path string) (err error) {
 	return
 }
 
+// DownloadFile downloads a file from a URL.
 func DownloadFile(url *url.URL, filePath string) (err error) {
 	resp, err := http.Get(url.String())
 	if err != nil {

util/lisp/lisp.go

@@ -1,3 +1,4 @@
+// Package lisp implements functions for working with the Clozure Common Lisp executables.
 package lisp
 
 import (

util/version/version.go

@@ -1,3 +1,4 @@
+// Package version simply stores the build version string set using "-ldflags".
 package version
 
 // BuildVersion will be replaced during the build process using "-ldflags".