Improve docs

Author: cvhariharan

cmd/dot/root.go

@@ -66,6 +66,7 @@ func init() {
 	rootCmd.AddCommand(versionCmd)
 }
 
+// Execute runs the root command for dot.
 func Execute() {
 	if err := rootCmd.Execute(); err != nil {
 		log.Fatal(err)

main.go

@@ -1,3 +1,6 @@
+// Dot is a local first CI system.
+//
+// Dot uses Docker to run jobs concurrently in stages. More info can be found at https://github.com/opnlabs/dot/wiki
 package main
 
 import (

pkg/models/models.go

@@ -1,13 +1,18 @@
 package models
 
 type Stage string
+
+// Variable represents a job variable as a key-value pair.
+// Variables are defined as an array of key-value pairs, so each Variable map only has 1 entry.
 type Variable map[string]any
 
+// JobFile represents the dot.yml file
 type JobFile struct {
 	Stages []Stage `yaml:"stages" validate:"required,dive"`
 	Jobs   []Job   `yaml:"jobs" validate:"required,dive"`
 }
 
+// Job represents a single job in a stage
 type Job struct {
 	Name       string     `yaml:"name" validate:"required"`
 	Src        string     `yaml:"src"`

pkg/runner/docker.go

@@ -1,3 +1,6 @@
+// Package runner implements the backend that executes the jobs.
+//
+// Docker runner uses the docker runtime to execute jobs.
 package runner
 
 import (

pkg/store/memorystore.go

@@ -1,3 +1,4 @@
+// Package store implements a simple key-value store.
 package store
 
 import (

pkg/utils/compress.go

@@ -1,3 +1,5 @@
+// Package utils provides some utility functions to compress and decompress tar and tar.gz.
+// It also provides a logger that can output in color and implements io.Writer.
 package utils
 
 import (
@@ -13,8 +15,7 @@ import (
 
 const MaxFileSizeBytes = 50 * 1024 * 1024 // 50MB
 
-// Compress takes a path to a file or directory and creates a .tar.gzip file
-// at the outputPath location
+// Compress takes a path to a file or directory and creates a .tar.gzip file at the outputPath location.
 func Compress(path, outputPath string) error {
 	tarFile, err := os.Create(filepath.Clean(outputPath))
 	if err != nil {
@@ -58,8 +59,7 @@ func Compress(path, outputPath string) error {
 	})
 }
 
-// Decompress takes a location to a .tar.gzip file and a base path and
-// decompresses the contents wrt the base path
+// Decompress takes a location to a .tar.gzip file and a base path and decompresses the contents wrt the base path.
 func Decompress(tarPath, baseDir string) error {
 	tarFile, err := os.Open(filepath.Clean(tarPath))
 	if err != nil {
@@ -107,8 +107,7 @@ func Decompress(tarPath, baseDir string) error {
 	}
 }
 
-// CompressTar takes a path to a file or directory and creates a .tar file
-// at the outputPath location
+// CompressTar takes a path to a file or directory and creates a .tar file at the outputPath location.
 func CompressTar(path, outputPath string) error {
 	tarFile, err := os.Create(filepath.Clean(outputPath))
 	if err != nil {
@@ -149,8 +148,7 @@ func CompressTar(path, outputPath string) error {
 	})
 }
 
-// DecompressTar takes a location to a .tar file and a base path and
-// decompresses the contents wrt the base path
+// DecompressTar takes a location to a .tar file and a base path and decompresses the contents wrt the base path.
 func DecompressTar(tarPath, baseDir string) error {
 	tarFile, err := os.Open(filepath.Clean(tarPath))
 	if err != nil {
@@ -192,7 +190,7 @@ func DecompressTar(tarPath, baseDir string) error {
 	}
 }
 
-// TarCopy uses tar archive to copy src to dst to preserve the folder structure
+// TarCopy uses tar archive to copy src to dst to preserve the folder structure.
 func TarCopy(src, dst, tempDir string) error {
 	f, err := os.CreateTemp(tempDir, "tarcopy-*.tar.gzip")
 	if err != nil {

pkg/utils/logger.go

@@ -14,6 +14,7 @@ var l sync.Mutex
 
 const MaxNameLength = 20
 
+// ColorLogger provides an io.Writer that can output in color.
 type ColorLogger struct {
 	name   string
 	writer io.Writer