docs: model package

model/types.go

@@ -1,14 +1,22 @@
+// Package model defines the data structures and associated functions used to represent
+// and manipulate the health data in the application. This includes defining formats for data entries,
+// calculations relevant to the metabolic tracking, and utilities for creating and handling these data
+// structures. This package serves as the central definition point for all data used in the application.
 package model
 
 import "time"
 
-// Note holds a text note along with the time the note was taken.
+// Note represents a text note marked with the time it was taken.
+// This structure can be used to store and retrieve anecdotal information that
+// may be relevant to the health data being tracked.
 type Note struct {
 	Time time.Time `json:"time"`
 	Text string    `json:"text"`
 }
 
-// NewNote returns a new Note
+// NewNote creates a new Note instance with the current time and the provided text.
+// The function is a constructor for Note type, allowing quick instantiation with
+// automated timestamping.
 func NewNote(text string) Note {
 	return Note{
 		Time: time.Now(),
@@ -16,7 +24,9 @@ func NewNote(text string) Note {
 	}
 }
 
-// Reading holds the glucose and ketone level measurements along with the time the measurements were taken.
+// Reading contains measurements for glucose and ketone levels taken at a specific time.
+// Each Reading instance also calculates the Glucose Ketone Index (GKI),
+// a key metric for managing metabolic health.
 type Reading struct {
 	Time    time.Time `json:"time"`
 	Glucose float64   `json:"glucose"`
@@ -24,8 +34,10 @@ type Reading struct {
 	GKI     float64   `json:"GKI"`
 }
 
-// NewReading creates and returns a new Reading instance with the provided glucose and ketone levels, and records
-// the current time. The glucose value should be provided in mg/dL, while the ketone level should be in mmol/L.
+// NewReading creates a new Reading instance capturing the current time, glucose level,
+// and ketone level. It also calculates the Glucose Ketone Index (GKI) based on the provided
+// measurements. Glucose values should be in mg/dL and ketone levels in mmol/L.
+// If the ketone level is zero, the GKI is set to zero to prevent division by zero.
 func NewReading(glucose, ketone float64) Reading {
 	var gki float64
 	if ketone == 0 {
@@ -42,7 +54,10 @@ func NewReading(glucose, ketone float64) Reading {
 	}
 }
 
-// Record holds a pointer to a Reading or Note.
+// Record represents a container that can hold either a Reading or a Note, but not both.
+// This type is used to conglomerate different types of entries in a unified format.
+// Each Record uses JSON tags to properly encode or decode either a Reading or a Note,
+// with omitted fields left out of the serialized form.
 type Record struct {
 	Reading *Reading `json:"reading,omitempty"`
 	Note    *Note    `json:"note,omitempty"`