Document all systems/sub-models, parameters and globals

CHANGELOG.md

@@ -13,6 +13,10 @@
 - Copy parameters when applying them to a model (#55)
 - Pre-calculate experiment parameter variations for reproducible randomization (#56)
 
+### Documentation
+
+- All exported types and functions are now documented (#64)
+
 ### Other
 
 - Random seed is written to ECS resource for analysis (#43, #44, #45)

_examples/doc.go

@@ -0,0 +1,2 @@
+// Examples for the usage of beecs as a library.
+package examples

_examples/weather/main.go

@@ -15,13 +15,13 @@ func main() {
 	// Use randomized builtin weather data.
 	p.ForagingPeriod = params.ForagingPeriod{
 		Files: []string{
-			"data/foraging-period/berlin2000.txt",
-			"data/foraging-period/berlin2001.txt",
-			"data/foraging-period/berlin2002.txt",
-			"data/foraging-period/berlin2003.txt",
-			"data/foraging-period/berlin2004.txt",
-			"data/foraging-period/berlin2005.txt",
-			"data/foraging-period/berlin2006.txt",
+			"foraging-period/berlin2000.txt",
+			"foraging-period/berlin2001.txt",
+			"foraging-period/berlin2002.txt",
+			"foraging-period/berlin2003.txt",
+			"foraging-period/berlin2004.txt",
+			"foraging-period/berlin2005.txt",
+			"foraging-period/berlin2006.txt",
 		},
 		Builtin:     true,
 		RandomYears: true,

_tests/doc.go

@@ -0,0 +1,4 @@
+// Validation of the beecs implementation against the original [BEEHAVE] model.
+//
+// [BEEHAVE]: https://beehave-model.net
+package tests

comp/doc.go

@@ -0,0 +1,5 @@
+// Package comp provides all ECS components required for the beecs model.
+//
+// Components are bundles of closely related state variables of model entities that are represented as ECS entities.
+// In beecs, these entities are forager squadrons and flower patches.
+package comp

comp/patch.go

@@ -3,20 +3,32 @@ package comp
 import "github.com/mlange-42/beecs/enum/interp"
 
 // PatchConfig for initialization of flower patches.
+//
+// Exactly one of ConstantPatch, SeasonalPatch and ScriptedPatch must be non-nil.
 type PatchConfig struct {
-	DistToColony  float64        // Distance to the colony [m].
+	// Distance to the colony [m].
+	DistToColony float64
+	// Configuration for patches with constant resources.
 	ConstantPatch *ConstantPatch `json:",omitempty"`
+	// Configuration for patches with simple seasonal resource dynamics.
 	SeasonalPatch *SeasonalPatch `json:",omitempty"`
+	// Configuration for patches with scripted/arbitrary resource dynamics.
 	ScriptedPatch *ScriptedPatch `json:",omitempty"`
 }
 
+// ConstantPatch configuration for patches with constant resources.
+//
+// Used in [PatchConfig], not used as a component directly.
 type ConstantPatch struct {
 	Nectar               float64 // Maximum of available nectar [L].
 	Pollen               float64 // Maximum of available pollen [kg].
 	NectarConcentration  float64 // Sucrose concentration in the nectar [mol/L].
 	DetectionProbability float64 // Detection probability, e.g. from BeeScout.
 }
 
+// SeasonalPatch configuration for patches with simple seasonal resource dynamics.
+//
+// Used in [PatchConfig], not used as a component directly.
 type SeasonalPatch struct {
 	SeasonShift int     // Shift of the season [d]
 	MaxNectar   float64 // Maximum of available nectar [L].
@@ -26,6 +38,9 @@ type SeasonalPatch struct {
 	DetectionProbability float64 // Detection probability, e.g. from BeeScout.
 }
 
+// ScriptedPatch configuration for patches with scripted/arbitrary resource dynamics.
+//
+// Used in [PatchConfig], not used as a component directly.
 type ScriptedPatch struct {
 	Nectar               [][2]float64 // Maximum of available nectar [L].
 	Pollen               [][2]float64 // Maximum of available pollen [kg].

data/doc.go

@@ -0,0 +1,2 @@
+// Package data contains model input data, embedded in the binary.
+package data

data/embed.go

@@ -0,0 +1,18 @@
+package data
+
+import "embed"
+
+// Embedded data for daily foraging hours.
+//
+// # Available data
+//
+//   - foraging-period/berlin2000.txt
+//   - foraging-period/berlin2001.txt
+//   - foraging-period/berlin2002.txt
+//   - foraging-period/berlin2003.txt
+//   - foraging-period/berlin2004.txt
+//   - foraging-period/berlin2005.txt
+//   - foraging-period/berlin2006.txt
+//
+//go:embed foraging-period
+var ForagingPeriod embed.FS

doc.go

@@ -0,0 +1,14 @@
+// Re-implementation of the [BEEHAVE] model
+// in [Go] using the [Arche] Entity Component System (ECS).
+//
+// # Most important packages:
+//
+//   - [github.com/mlange-42/beecs/comp] -- Components
+//   - [github.com/mlange-42/beecs/sys] -- Systems / sub-models
+//   - [github.com/mlange-42/beecs/params] -- Model parameters
+//   - [github.com/mlange-42/beecs/globals] -- Global state variables
+//
+// [BEEHAVE]: https://beehave-model.net
+// [Go]: https://go.dev
+// [Arche]: https://github.com/mlange-42/arche
+package beecs

enum/interp/docs.go → enum/interp/doc.go

@@ -1,9 +1,12 @@
 // Package interp provides an enumeration of interpolation methods.
 package interp
 
+// Interpolation type alias for use as enumeration.
 type Interpolation uint8
 
 const (
+	// Step-wise interpolation.
 	Step Interpolation = iota
+	// Linear interpolation.
 	Linear
 )

experiment/experiment.go

@@ -14,7 +14,8 @@ type Experiment struct {
 	runsPerSet    int
 }
 
-// New creates a new Experiment with the given parameter variations and PRNG instance.
+// New creates a new Experiment with the given parameter variations,
+// PRNG instance and number of runs per parameter set.
 func New(vars []ParameterVariation, rng *rand.Rand, runs int) (Experiment, error) {
 	pars := []string{}
 	f := []ParameterFunction{}