Add godoc documentation to exported types and methods

Add proper godoc comments to exported items in:
- internal/globals: Appname, Version, Commit variables; Globals type; New function
- internal/log: LogLevel type; level constants; Config type; Initialize, Fatal,
  Error, Warn, Notice, Info, Debug functions and variants; TTYHandler type and
  methods; Module variable; LogOptions type

internal/globals/globals.go

@@ -4,13 +4,16 @@ import (
 	"time"
 )
 
-// these get populated from main() and copied into the Globals object.
-var (
-	Appname string = "vaultik"
-	Version string = "dev"
-	Commit  string = "unknown"
-)
+// Appname is the application name, populated from main().
+var Appname string = "vaultik"
 
+// Version is the application version, populated from main().
+var Version string = "dev"
+
+// Commit is the git commit hash, populated from main().
+var Commit string = "unknown"
+
+// Globals contains application-wide configuration and metadata.
 type Globals struct {
 	Appname   string
 	Version   string
@@ -18,6 +21,7 @@ type Globals struct {
 	StartTime time.Time
 }
 
+// New creates and returns a new Globals instance initialized with the package-level variables.
 func New() (*Globals, error) {
 	return &Globals{
 		Appname: Appname,

internal/log/log.go

@@ -12,19 +12,25 @@ import (
 	"golang.org/x/term"
 )
 
-// LogLevel represents the logging level
+// LogLevel represents the logging level.
 type LogLevel int
 
 const (
+	// LevelFatal represents a fatal error level that will exit the program.
 	LevelFatal LogLevel = iota
+	// LevelError represents an error level.
 	LevelError
+	// LevelWarn represents a warning level.
 	LevelWarn
+	// LevelNotice represents a notice level (mapped to Info in slog).
 	LevelNotice
+	// LevelInfo represents an informational level.
 	LevelInfo
+	// LevelDebug represents a debug level.
 	LevelDebug
 )
 
-// Logger configuration
+// Config holds logger configuration.
 type Config struct {
 	Verbose bool
 	Debug   bool
@@ -33,7 +39,7 @@ type Config struct {
 
 var logger *slog.Logger
 
-// Initialize sets up the global logger based on the provided configuration
+// Initialize sets up the global logger based on the provided configuration.
 func Initialize(cfg Config) {
 	// Determine log level based on configuration
 	var level slog.Level
@@ -76,7 +82,7 @@ func getCaller(skip int) string {
 	return fmt.Sprintf("%s:%d", filepath.Base(file), line)
 }
 
-// Fatal logs a fatal error and exits
+// Fatal logs a fatal error message and exits the program with code 1.
 func Fatal(msg string, args ...any) {
 	if logger != nil {
 		// Add caller info to args
@@ -86,12 +92,12 @@ func Fatal(msg string, args ...any) {
 	os.Exit(1)
 }
 
-// Fatalf logs a formatted fatal error and exits
+// Fatalf logs a formatted fatal error message and exits the program with code 1.
 func Fatalf(format string, args ...any) {
 	Fatal(fmt.Sprintf(format, args...))
 }
 
-// Error logs an error
+// Error logs an error message.
 func Error(msg string, args ...any) {
 	if logger != nil {
 		args = append(args, "caller", getCaller(2))
@@ -99,12 +105,12 @@ func Error(msg string, args ...any) {
 	}
 }
 
-// Errorf logs a formatted error
+// Errorf logs a formatted error message.
 func Errorf(format string, args ...any) {
 	Error(fmt.Sprintf(format, args...))
 }
 
-// Warn logs a warning
+// Warn logs a warning message.
 func Warn(msg string, args ...any) {
 	if logger != nil {
 		args = append(args, "caller", getCaller(2))
@@ -112,12 +118,12 @@ func Warn(msg string, args ...any) {
 	}
 }
 
-// Warnf logs a formatted warning
+// Warnf logs a formatted warning message.
 func Warnf(format string, args ...any) {
 	Warn(fmt.Sprintf(format, args...))
 }
 
-// Notice logs a notice (mapped to Info level)
+// Notice logs a notice message (mapped to Info level).
 func Notice(msg string, args ...any) {
 	if logger != nil {
 		args = append(args, "caller", getCaller(2))
@@ -125,12 +131,12 @@ func Notice(msg string, args ...any) {
 	}
 }
 
-// Noticef logs a formatted notice
+// Noticef logs a formatted notice message.
 func Noticef(format string, args ...any) {
 	Notice(fmt.Sprintf(format, args...))
 }
 
-// Info logs an info message
+// Info logs an informational message.
 func Info(msg string, args ...any) {
 	if logger != nil {
 		args = append(args, "caller", getCaller(2))
@@ -138,12 +144,12 @@ func Info(msg string, args ...any) {
 	}
 }
 
-// Infof logs a formatted info message
+// Infof logs a formatted informational message.
 func Infof(format string, args ...any) {
 	Info(fmt.Sprintf(format, args...))
 }
 
-// Debug logs a debug message
+// Debug logs a debug message.
 func Debug(msg string, args ...any) {
 	if logger != nil {
 		args = append(args, "caller", getCaller(2))
@@ -151,12 +157,12 @@ func Debug(msg string, args ...any) {
 	}
 }
 
-// Debugf logs a formatted debug message
+// Debugf logs a formatted debug message.
 func Debugf(format string, args ...any) {
 	Debug(fmt.Sprintf(format, args...))
 }
 
-// With returns a logger with additional context
+// With returns a logger with additional context attributes.
 func With(args ...any) *slog.Logger {
 	if logger != nil {
 		return logger.With(args...)
@@ -164,12 +170,12 @@ func With(args ...any) *slog.Logger {
 	return slog.Default()
 }
 
-// WithContext returns a logger with context
+// WithContext returns a logger with the provided context.
 func WithContext(ctx context.Context) *slog.Logger {
 	return logger
 }
 
-// Logger returns the underlying slog.Logger
+// Logger returns the underlying slog.Logger instance.
 func Logger() *slog.Logger {
 	return logger
 }

internal/log/module.go

@@ -4,19 +4,19 @@ import (
 	"go.uber.org/fx"
 )
 
-// Module exports logging functionality
+// Module exports logging functionality for dependency injection.
 var Module = fx.Module("log",
 	fx.Invoke(func(cfg Config) {
 		Initialize(cfg)
 	}),
 )
 
-// New creates a new logger configuration from provided options
+// New creates a new logger configuration from provided options.
 func New(opts LogOptions) Config {
 	return Config(opts)
 }
 
-// LogOptions are provided by the CLI
+// LogOptions are provided by the CLI.
 type LogOptions struct {
 	Verbose bool
 	Debug   bool

internal/log/tty_handler.go

@@ -21,14 +21,14 @@ const (
 	colorBold   = "\033[1m"
 )
 
-// TTYHandler is a custom handler for TTY output with colors
+// TTYHandler is a custom slog handler for TTY output with colors.
 type TTYHandler struct {
 	opts slog.HandlerOptions
 	mu   sync.Mutex
 	out  io.Writer
 }
 
-// NewTTYHandler creates a new TTY handler
+// NewTTYHandler creates a new TTY handler with colored output.
 func NewTTYHandler(out io.Writer, opts *slog.HandlerOptions) *TTYHandler {
 	if opts == nil {
 		opts = &slog.HandlerOptions{}
@@ -39,12 +39,12 @@ func NewTTYHandler(out io.Writer, opts *slog.HandlerOptions) *TTYHandler {
 	}
 }
 
-// Enabled reports whether the handler handles records at the given level
+// Enabled reports whether the handler handles records at the given level.
 func (h *TTYHandler) Enabled(_ context.Context, level slog.Level) bool {
 	return level >= h.opts.Level.Level()
 }
 
-// Handle writes the log record
+// Handle writes the log record to the output with color formatting.
 func (h *TTYHandler) Handle(_ context.Context, r slog.Record) error {
 	h.mu.Lock()
 	defer h.mu.Unlock()
@@ -103,12 +103,12 @@ func (h *TTYHandler) Handle(_ context.Context, r slog.Record) error {
 	return nil
 }
 
-// WithAttrs returns a new handler with the given attributes
+// WithAttrs returns a new handler with the given attributes.
 func (h *TTYHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
 	return h // Simplified for now
 }
 
-// WithGroup returns a new handler with the given group name
+// WithGroup returns a new handler with the given group name.
 func (h *TTYHandler) WithGroup(name string) slog.Handler {
 	return h // Simplified for now
 }