doc: Additional doc strings

db/task.go

@@ -159,6 +159,7 @@ func (task *Task) PrettyAge(duration time.Duration) string {
 	return strings.TrimSuffix(pretty, "0s")
 }
 
+// AgeTime returns the time since the task was created
 func (task *Task) AgeTime() time.Duration {
 	var createdAt, err = time.Parse(SQLITE_TIME_FORMAT, task.CreatedUtc)
 	if err != nil {
@@ -168,14 +169,17 @@ func (task *Task) AgeTime() time.Duration {
 	return time.Since(createdAt)
 }
 
+// AgeStr returns the pretty version of the time since the task was created
 func (task *Task) AgeStr() string {
 	return task.PrettyAge(task.AgeTime())
 }
 
+// IsStarted returns true if the task is in progress
 func (task *TaskDetailed) IsStarted() bool {
 	return task.Inprogress
 }
 
+// UrgencyStr returns the string version of the Urgency Float
 func (task *TaskDetailed) UrgencyStr() string {
 	var urgency = task.Urgency()
 	if urgency > 10.0 {
@@ -184,6 +188,7 @@ func (task *TaskDetailed) UrgencyStr() string {
 	return fmt.Sprintf("%.2f", task.Urgency())
 }
 
+// PrettyCumTime returns the pretty version of the CumulativeTime
 func (task *TaskDetailed) PrettyCumTime() string {
 	if !task.CumulativeTime.Valid {
 		return ""
@@ -196,13 +201,15 @@ func (task *TaskDetailed) PrettyCumTime() string {
 	return task.PrettyAge(duration)
 }
 
+// Urgency returns the urgency of the task based on the task's properties (will be cached)
 func (task *TaskDetailed) Urgency() float64 {
 	if task.urgencyComputed == 0.0 {
 		task.urgencyComputed = task.urgency()
 	}
 	return task.urgencyComputed
 }
 
+// UrgencyColourAnsiBackground returns the ANSI background colour for the task urgency
 func (task *TaskDetailed) UrgencyColourAnsiBackground() string {
 	var urgency = task.Urgency()
 	if urgency > 10.0 {
@@ -214,6 +221,7 @@ func (task *TaskDetailed) UrgencyColourAnsiBackground() string {
 	return "232" // BLACK
 }
 
+// UrgencyColourAnsiForeground returns the ANSI foreground colour for the task urgency
 func (task *TaskDetailed) UrgencyColourAnsiForeground() string {
 	return "255" // WHITE
 }
@@ -329,6 +337,7 @@ func (task *TaskDetailed) urgencyDue() float64 {
 	}
 }
 
+// CountTasks returns the total number of tasks in the database
 func (store *Store) CountTasks(ctx context.Context) (int64, error) {
 	var sql = `SELECT COUNT(*) FROM tasks`
 	var count int64
@@ -339,6 +348,8 @@ func (store *Store) CountTasks(ctx context.Context) (int64, error) {
 	}
 	return count, nil
 }
+
+// ListTasks returns a list of all tasks in the database
 func (store *Store) ListTasks(ctx context.Context) ([]TaskDetailed, error) {
 	var sql = `
 	SELECT
@@ -413,6 +424,7 @@ func (store *Store) ListTasks(ctx context.Context) ([]TaskDetailed, error) {
 	return tasks, nil
 }
 
+// DeleteTaskById deletes a task by its ID
 func (store *Store) DeleteTaskById(ctx context.Context, id int64) (bool, error) {
 	var err error
 	var res sql.Result
@@ -428,6 +440,7 @@ func (store *Store) DeleteTaskById(ctx context.Context, id int64) (bool, error)
 	return rowsAffected > 0, nil
 }
 
+// CreateTask creates a new task in the database
 func (store *Store) CreateTask(ctx context.Context, task *Task) (*Task, error) {
 	var sql = `
 	INSERT INTO tasks
@@ -455,6 +468,7 @@ func (store *Store) CreateTask(ctx context.Context, task *Task) (*Task, error) {
 	return newTask, nil
 }
 
+// CompleteTaskById marks a task as completed by its ID
 func (store *Store) CompleteTaskById(taskId int64) (bool, error) {
 	var sql = `
 	UPDATE tasks
@@ -482,6 +496,7 @@ func (store *Store) CompleteTaskById(taskId int64) (bool, error) {
 	return affected > 0, nil
 }
 
+// IncreasePriority increases the priority of a task by its ID (if possible)
 func (store *Store) IncreasePriority(ctx context.Context, id int64) (bool, error) {
 	var sql = `
 	UPDATE tasks
@@ -506,6 +521,7 @@ func (store *Store) IncreasePriority(ctx context.Context, id int64) (bool, error
 	return affected == 1, err
 }
 
+// DecreasePriority decreases the priority of a task by its ID (if possible)
 func (store *Store) DecreasePriority(ctx context.Context, id int64) (bool, error) {
 	var sql = `
 	UPDATE tasks
@@ -530,6 +546,7 @@ func (store *Store) DecreasePriority(ctx context.Context, id int64) (bool, error
 	return affected == 1, err
 }
 
+// SetPriority sets the priority of a task by its ID
 func (store *Store) SetPriority(ctx context.Context, id int64, priority TaskPriority) (bool, error) {
 	var sql = `UPDATE tasks SET priority = ? WHERE id = ?`
 	var res, err = store.Con.ExecContext(ctx, sql, priority, id)
@@ -543,6 +560,7 @@ func (store *Store) SetPriority(ctx context.Context, id int64, priority TaskPrio
 	return affected == 1, err
 }
 
+// GetTaskByIdOrPanic returns a task by its ID or panics (ONLY FOR TESTING)
 func (store *Store) GetTaskByIdOrPanic(id int64) *Task {
 	var sql = `SELECT * FROM tasks WHERE id = ?`
 	var task = &Task{}
@@ -553,20 +571,29 @@ func (store *Store) GetTaskByIdOrPanic(id int64) *Task {
 	return task
 }
 
+// SetTaskStateToCompleted marks a task as completed by its ID
 func (store *Store) SetTaskStateToStarted(taskId int64) error {
 	return store.SetTaskState(taskId, TaskStateStarted)
 }
 
+// SetTaskStateToIncomplete marks a task as incomplete by its ID
 func (store *Store) SetTaskStateToIncomplete(taskId int64) error {
 	return store.SetTaskState(taskId, TaskStateIncomplete)
 }
 
+// SetTaskStateToCompleted marks a task as completed by its ID
+func (store *Store) SetTaskStateToCompleted(taskId int64) error {
+	return store.SetTaskState(taskId, TaskStateCompleted)
+}
+
+// SetTaskState sets the state of a task by its ID
 func (store *Store) SetTaskState(taskId int64, state TaskState) error {
 	var sql = `UPDATE tasks SET state = ? WHERE id = ?; `
 	_, err := store.Con.Exec(sql, state, taskId)
 	return err
 }
 
+// GetTaskById returns a task by its ID
 func (store *Store) GetTaskById(ctx context.Context, taskId int64) (*Task, error) {
 	var sql = `SELECT * FROM tasks WHERE id = ?`
 	var task = &Task{}
@@ -577,6 +604,7 @@ func (store *Store) GetTaskById(ctx context.Context, taskId int64) (*Task, error
 	return task, err
 }
 
+// TaskIdExistsAndNotCompleted returns true if a task exists and is not completed
 func (store *Store) TaskIdExistsAndNotCompleted(tx *sqlx.Tx, taskId int64) bool {
 	var sql = `SELECT EXISTS(
 	    SELECT 1
@@ -589,6 +617,7 @@ func (store *Store) TaskIdExistsAndNotCompleted(tx *sqlx.Tx, taskId int64) bool
 	return err == nil
 }
 
+// FilterByTaskId returns a task by its ID
 func (store *Store) FilterByTaskId(taskId int64, tasks []TaskDetailed) *TaskDetailed {
 	for _, task := range tasks {
 		if task.ID == taskId {
@@ -598,6 +627,7 @@ func (store *Store) FilterByTaskId(taskId int64, tasks []TaskDetailed) *TaskDeta
 	return nil
 }
 
+// TaskToggleNext toggles the next flag of a task by its ID
 func (store *Store) TaskToggleNextTx(tx *sqlx.Tx, taskId int64) error {
 	var sql = `UPDATE tasks SET next = case when next = 0 then 1 else 0 end WHERE id = ?`
 	_, err := tx.Exec(sql, taskId)

db/task_dep.go

@@ -18,10 +18,11 @@ PRAGMA user_version = 10;
 `
 
 type TaskDependency struct {
-	TaskID      int64 `db:"taskId"`
-	DependsOnID int64 `db:"dependsOnId"`
+	TaskID      int64 `db:"taskId"` // Unique identifier of the task
+	DependsOnID int64 `db:"dependsOnId"` // Unique identifier of the task that this task depends on
 }
 
+// TaskDependsOn creates a dependency between two tasks
 func (store *Store) TaskDependsOnTx(tx *sqlx.Tx, taskId int64, dependsOnId int64) error {
 	var _, err = tx.Exec(`INSERT INTO taskDependencies (taskId, dependsOnId) VALUES (?, ?)`, taskId, dependsOnId)
 	if err != nil {
@@ -30,12 +31,14 @@ func (store *Store) TaskDependsOnTx(tx *sqlx.Tx, taskId int64, dependsOnId int64
 	return nil
 }
 
+// GetDependenciesForTask returns all the dependencies for a task
 func (store *Store) GetDependenciesForTask(taskId int64) ([]TaskDependency, error) {
 	var deps []TaskDependency
 	err := store.Con.Select(&deps, `SELECT * FROM taskDependencies WHERE taskId = ?`, taskId)
 	return deps, err
 }
 
+// DeleteDependenciesForTask deletes all dependencies for a task
 func (store *Store) DeleteDependenciesForCompletedTask(completedTaskId int64) error {
 	_, err := store.Con.Exec(`DELETE FROM taskDependencies WHERE taskId = ? OR dependsOnId = ?`, completedTaskId, completedTaskId)
 	if err != nil {

db/task_projects.go

@@ -14,16 +14,19 @@ CREATE TABLE IF NOT EXISTS taskProjects (
 PRAGMA user_version = 6;
 `
 
+// TaskProjectLink is a struct that represents a link between a task and a project
 type TaskProjectLink struct {
 	TaskID    int64 `db:"taskId"`
 	ProjectID int64 `db:"projectId"`
 }
 
+// ProjectLinkTaskTx will link a task to a project
 func (s *Store) ProjectLinkTaskTx(tx *sqlx.Tx, projectId, taskId int64) error {
 	var _, err = tx.Exec(`INSERT INTO taskProjects (projectId, taskId) VALUES (?, ?)`, projectId, taskId)
 	return err
 }
 
+// ProjectUnlinkTaskTx will unlink a task from a project
 func (s *Store) ProjectTasksList() ([]TaskProjectLink, error) {
 	var links []TaskProjectLink
 	err := s.Con.Select(&links, `SELECT * FROM taskProjects`)

db/task_track.go

@@ -18,14 +18,16 @@ CREATE TABLE IF NOT EXISTS taskTime (
 PRAGMA user_version = 8;
 `
 
+// TaskTime represents the time tracking for a task
 type TaskTime struct {
-	Id           int64          `db:"id"`
-	TaskId       int64          `db:"taskId"`
-	StartTimeUtc string         `db:"startTimeUtc"`
-	EndTimeUtc   sql.NullString `db:"endTimeUtc"`
-	TotalTime    sql.NullString `db:"totalTime"`
+	Id           int64          `db:"id"`           // Unique identifier
+	TaskId       int64          `db:"taskId"`       // Unique identifier of the task
+	StartTimeUtc string         `db:"startTimeUtc"` // Start time in UTC
+	EndTimeUtc   sql.NullString `db:"endTimeUtc"`   // End time in UTC
+	TotalTime    sql.NullString `db:"totalTime"`    // Total time in seconds
 }
 
+// StartTrackingTaskTime will start tracking time for a task
 func (store *Store) StartTrackingTaskTime(ctx context.Context, taskId int64) error {
 	// 1. Set the task state to started
 	// 2. If there are no times for the task, insert a new time
@@ -56,6 +58,7 @@ func (store *Store) StartTrackingTaskTime(ctx context.Context, taskId int64) err
 	return tx.Commit()
 }
 
+// StopTrackingTaskTime will stop tracking time for a task
 func (store *Store) StopTrackingTaskTime(ctx context.Context, id int64) error {
 	var sql = `UPDATE tasks SET state = 0 WHERE id = ?;`
 	var tx, err = store.Con.Beginx()
@@ -85,6 +88,7 @@ func (store *Store) StopTrackingTaskTime(ctx context.Context, id int64) error {
 	return tx.Commit()
 }
 
+// GetTaskTimes will get all the times for a task
 func (store *Store) GetTaskTimes(ctx context.Context, taskId int64) ([]TaskTime, error) {
 	var sql = `SELECT * FROM taskTime WHERE taskId = ?;`
 	var rows, err = store.Con.QueryxContext(ctx, sql, taskId)
@@ -103,6 +107,7 @@ func (store *Store) GetTaskTimes(ctx context.Context, taskId int64) ([]TaskTime,
 	return taskTimes, nil
 }
 
+// GetCumTime will get the cumulative time for a task
 func (store *Store) GetCumTime(ctx context.Context, taskId int64) (int64, error) {
 	var sql = `
 	SELECT

events/delete.go

@@ -3,9 +3,14 @@ package events
 // ============================================================================
 // COMPLETE BY ID
 // ============================================================================
+
+// CompleteTaskById is an event that is used to complete a task by its ID
 type CompleteTaskById struct{ Id int64 }
 
+// CompleteTaskById is an event that is used to complete a task by its ID
 func DecodeCompletedTaskById(e *Event) *CompleteTaskById { return e.Data.(*CompleteTaskById) }
+
+// NewCompleteEvent will create a new event to complete a task by its ID
 func NewCompleteEvent(id int64) *Event {
 	return &Event{
 		Type: EventCompleteTaskById,
@@ -16,10 +21,14 @@ func NewCompleteEvent(id int64) *Event {
 // ============================================================================
 // DELETE BY ID
 // ============================================================================
+
+// DeleteTaskById is an event that is used to delete a task by its ID
 type DeleteTaskById struct{ Id int64 }
 
+// DecodeDeleteTaskByIdEvent will decode the event to delete a task by its ID
 func DecodeDeleteTaskByIdEvent(e *Event) *DeleteTaskById { return e.Data.(*DeleteTaskById) }
 
+// DeleteTaskById is an event that is used to delete a task by its ID
 func NewDeleteTaskByIdEvent(id int64) *Event {
 	return &Event{
 		Type: EventDeleteTaskById,

events/error.go

@@ -1,12 +1,12 @@
 package events
 
-// ============================================================================
-// DELETE BY ID
-// ============================================================================
+// NewErrorEvent will create a new event that is used to report an error
 func NewErrorEvent(error error) *Event {
 	return &Event{
 		Type: EventError,
 		Data: error,
 	}
 }
+
+// DecodeErrorEvent will decode the event to report an error
 func DecodeErrorEvent(e *Event) error { return e.Data.(error) }

events/event.go

@@ -1,23 +1,23 @@
 package events
 
-type EventType string
+type EventType string // EventType is a type of event
 
 const (
-	EventError            EventType = "Error"
-	EventRunProgram       EventType = "RunProgram"
-	EventListTasks        EventType = "ListTasks"
-	EventCompleteTaskById EventType = "CompleteTaskByID"
-	EventTableFuzzySearch EventType = "TableFuzzySearch"
-	EventDeleteTaskById   EventType = "DeleteTaskByID"
-	EventStartTaskById    EventType = "StartTask"
-	EventStopTaskById     EventType = "StopTask"
-	EventListTaskResponse EventType = "ListTaskResponse"
-	EventIncreasePriority EventType = "IncreaseTaskPriority"
-	EventDecreasePriority EventType = "DecreaseTaskPriority"
-	EventSetPriority      EventType = "SetTaskPriority"
+	EventError            EventType = "Error"                // Error event
+	EventRunProgram       EventType = "RunProgram"           // RunProgram e.g 'add task'
+	EventListTasks        EventType = "ListTasks"            // ListTasks event
+	EventCompleteTaskById EventType = "CompleteTaskByID"     // Mark a task as complete
+	EventTableFuzzySearch EventType = "TableFuzzySearch"     // Fuzzy search for a task
+	EventDeleteTaskById   EventType = "DeleteTaskByID"       // Delete a task
+	EventStartTaskById    EventType = "StartTask"            // Start a task
+	EventStopTaskById     EventType = "StopTask"             // Stop a task
+	EventListTaskResponse EventType = "ListTaskResponse"     // List tasks responses to be consumed by the UI
+	EventIncreasePriority EventType = "IncreaseTaskPriority" // Increase the priority of a task
+	EventDecreasePriority EventType = "DecreaseTaskPriority" // Decrease the priority of a task
+	EventSetPriority      EventType = "SetTaskPriority"      // Set the priority of a task
 )
 
 type Event struct {
-	Type EventType
-	Data interface{}
+	Type EventType   // Type of event
+	Data interface{} // Data associated with the event (payload)
 }

events/filter.go

@@ -3,9 +3,14 @@ package events
 // ============================================================================
 // COMPLETE BY ID
 // ============================================================================
+
+// TableFuzzySearch Is an event that is used to search a table by a fuzzy search
 type TableFuzzySearch struct{ Match string }
 
+// DecodeTableFuzzySearch will decode the event to search a table by a fuzzy search
 func DecodeTableFuzzySearch(e *Event) *TableFuzzySearch { return e.Data.(*TableFuzzySearch) }
+
+// NewTableFuzzySearch will create a new event to search a table by a fuzzy search
 func NewTableFuzzySearch(match string) *Event {
 	return &Event{
 		Type: EventTableFuzzySearch,