doc: add and improve comments

internal/metadata/version.go

@@ -2,5 +2,5 @@ package metadata
 
 import "strings"
 
-const GoTomatoVersion = "v0.0.4" // The GoTomato Version
-var ProtocolVersion = strings.Split(GoTomatoVersion, ".")[0]
+const GoTomatoVersion = "v0.0.4"                             // The GoTomato version
+var ProtocolVersion = strings.Split(GoTomatoVersion, ".")[0] // The protocol version

internal/pomodoro/pomodoro.go

@@ -11,6 +11,8 @@ import (
 var mu sync.Mutex // to synchronize access to shared state
 var timer Timer
 
+// Update `State` with the remaining seconds of the passed timer
+// until the timer sends an End or Abort signal
 func waitForTimer(t Timer) bool {
 	for {
 		select {
@@ -24,7 +26,7 @@ func waitForTimer(t Timer) bool {
 	}
 }
 
-// RunPomodoro iterates the Pomodoro work/break sessions.
+// RunPomodoro iterates the Pomodoro work/break sessions
 func RunPomodoro() {
 	mu.Lock()
 	shared.State.Ongoing = true
@@ -38,12 +40,14 @@ func RunPomodoro() {
 
 		shared.State.Session = session
 
+		// Work
 		shared.State.Mode = "Work"
 		go timer.Start(pomodoroConfig.Work)
 		if !waitForTimer(timer) {
 			break
 		}
 
+		// Breaks
 		if session < pomodoroConfig.Sessions {
 			shared.State.Mode = "ShortBreak"
 			go timer.Start(pomodoroConfig.ShortBreak)
@@ -56,6 +60,8 @@ func RunPomodoro() {
 			if !waitForTimer(timer) {
 				break
 			}
+
+			// send "End" state for one second
 			shared.State.Mode = "End"
 			time.Sleep(time.Second)
 		}
@@ -92,13 +98,13 @@ func ResumePomodoro() {
 
 func IsPomodoroOngoing() bool {
 	mu.Lock()
-	defer mu.Unlock() // Ensures that the mutex is unlocked after the function is done
+	defer mu.Unlock()
 	return shared.State.Ongoing
 }
 
 func IsPomodoroPaused() bool {
 	mu.Lock()
-	defer mu.Unlock() // Ensures that the mutex is unlocked after the function is done
+	defer mu.Unlock()
 	return shared.State.Paused
 }
 

internal/pomodoro/timer.go

@@ -2,15 +2,17 @@ package pomodoro
 
 import "time"
 
+// Represents a timer
 type Timer struct {
-	TimeLeft chan int  // time left
+	TimeLeft chan int  // signals time left on every second
 	End      chan bool // signal on successful end
 	Abort    chan bool // signal on premature end
-	stop     chan bool
-	wait     chan bool
-	resume   chan bool
+	stop     chan bool // internal channel
+	wait     chan bool // internal channel
+	resume   chan bool // internal channel
 }
 
+// Initializes a new timer with fresh channels
 func (t Timer) Init() Timer {
 	return Timer{
 		TimeLeft: make(chan int),
@@ -22,6 +24,7 @@ func (t Timer) Init() Timer {
 	}
 }
 
+// Start the timer
 func (t *Timer) Start(duration int) {
 	tick := time.NewTicker(time.Second)
 	for timeLeft := duration; timeLeft > 0; {

internal/shared/configDefaults.go

@@ -2,11 +2,13 @@ package shared
 
 import "git.smsvc.net/pomodoro/GoTomato/pkg/models"
 
+// The default server config if nothing else is set
 var DefaultServerConfig = models.ServerConfig{
 	ListenAddress: "0.0.0.0",
 	ListenPort:    8080,
 }
 
+// The default pomodoro config if nothing else is set
 var DefaultPomodoroConfig = models.PomodoroConfig{
 	Work:       25 * 60,
 	ShortBreak: 5 * 60,

internal/shared/state.go

@@ -5,6 +5,7 @@ import (
 	"git.smsvc.net/pomodoro/GoTomato/pkg/models"
 )
 
+// The global state of the pomodoro
 var State = models.ServerMessage{
 	Mode:            "Idle",
 	Settings:        DefaultPomodoroConfig,
@@ -15,4 +16,5 @@ var State = models.ServerMessage{
 	ProtocolVersion: metadata.ProtocolVersion,
 }
 
+// The password needed to execute client commands or change the pomodoro config
 var PomodoroPassword string

internal/websocket/broadcast.go

@@ -9,7 +9,7 @@ import (
 	"git.smsvc.net/pomodoro/GoTomato/internal/shared"
 )
 
-// sends continous messages to all connected WebSocket clients.
+// Sends continous messages to all connected WebSocket clients
 func SendPermanentBroadCastMessage() {
 	tick := time.NewTicker(time.Second)
 	for {

internal/websocket/client_commands.go

@@ -10,7 +10,7 @@ import (
 	"git.smsvc.net/pomodoro/GoTomato/pkg/models"
 )
 
-// handleClientCommands listens for commands from WebSocket clients
+// Listens for commands from a client and handles them
 func handleClientCommands(ws *websocket.Conn) {
 	for {
 		var clientCommand models.ClientCommand

internal/websocket/handle_connection.go

@@ -13,12 +13,12 @@ import (
 var Clients = make(map[*websocket.Conn]*models.Client)
 var mu sync.Mutex // Mutex to protect access to the Clients map
 
-// Upgrader to upgrade HTTP requests to WebSocket connections
+// Upgrade HTTP requests to WebSocket connections
 var upgrader = websocket.Upgrader{
 	CheckOrigin: func(r *http.Request) bool { return true },
 }
 
-// HandleConnection upgrades HTTP requests to WebSocket connections and manages the client lifecycle.
+// Upgrades HTTP requests to WebSocket connections and manages the client lifecycle
 func HandleConnection(w http.ResponseWriter, r *http.Request) {
 	// Upgrade initial GET request to a WebSocket
 	ws, err := upgrader.Upgrade(w, r, nil)