From 62b487ed9da06cd564237ef4df81cf2cffa11af9 Mon Sep 17 00:00:00 2001
From: Paul Buetow <paul@buetow.org>
Date: Wed, 25 Mar 2026 00:00:40 +0200
Subject: cmd/gt: add comprehensive package documentation

- Enhanced Package gt documentation with detailed usage examples for percentage calculations and RPN expressions
- Added architecture overview section
- Enhanced Package internal documentation with version format, build instructions, and usage examples
- All tests pass and application builds correctly
---
 cmd/gt/main.go | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 58 insertions(+), 2 deletions(-)

(limited to 'cmd')

diff --git a/cmd/gt/main.go b/cmd/gt/main.go
index 795dbe9..c571792 100644
--- a/cmd/gt/main.go
+++ b/cmd/gt/main.go
@@ -1,3 +1,46 @@
+// Package gt provides a command-line percentage calculator with RPN support.
+//
+// gt is a versatile calculator that supports both percentage calculations and
+// Reverse Polish Notation (RPN) expressions. It can be used in two modes:
+//
+// 1. Command-line mode: Pass calculations as arguments
+//    gt 20% of 150         # Calculate 20% of 150
+//    gt 3 4 +              # RPN expression: 3 + 4
+//
+// 2. Interactive REPL mode: Run without arguments to start an interactive session
+//    gt                    # Start interactive REPL
+//
+// Percentage Calculations
+//
+// The calculator supports various percentage formats:
+//   - Basic percentage: "20% of 150" → 30
+//   - With prefix: "what is 20% of 150" → 30
+//   - Reverse percentage: "30 is what % of 150" → 20%
+//   - Find base: "30 is 20% of what" → 150
+//
+// RPN (Reverse Polish Notation) Support
+//
+// RPN expressions use postfix notation where operators follow operands:
+//   - Basic operations: "3 4 +" (3 + 4), "5 2 -" (5 - 2)
+//   - Complex expressions: "3 4 + 4 4 - *" ((3 + 4) * (4 - 4))
+//   - Exponentiation: "2 3 ^" (2^3 = 8)
+//   - Variable assignment: "x 5 = x x +" (assign x=5, then x + x)
+//   - Stack operations: "dup swap pop show"
+//
+// Error Handling
+//
+// Errors from calculations or parsing are printed to stdout with exit code 1.
+// Invalid RPN expressions and malformed percentage queries both return errors.
+//
+// Architecture
+//
+// The package uses a layered architecture:
+//   - main.go: Entry point and command routing
+//   - calculator/: Handles percentage calculation parsing
+//   - rpn/: Handles RPN expression parsing and evaluation
+//   - repl/: Provides interactive Read-Eval-Print Loop mode
+//
+// See the cmd/gt/internal package for version information.
 package main
 
 import (
@@ -12,6 +55,7 @@ import (
 	"github.com/mattn/go-isatty"
 )
 
+// main is the entry point for the gt command-line calculator.
 func main() {
 	output, err := runCommand(os.Args)
 	if err != nil {
@@ -21,6 +65,12 @@ func main() {
 	fmt.Println(output)
 }
 
+// runCommand processes command-line arguments and executes the appropriate action.
+//
+// It handles:
+//   - No arguments: Start REPL mode if stdin is a TTY, otherwise show usage
+//   - "version" argument: Return the version string
+//   - Other arguments: Try RPN parsing first, then fall back to percentage calculation
 func runCommand(args []string) (string, error) {
 	if len(args) < 2 {
 		// No args provided - check if stdin is a TTY for REPL mode
@@ -55,7 +105,9 @@ func runCommand(args []string) (string, error) {
 	return result, nil
 }
 
-// runREPL runs the REPL and handles errors
+// runREPL starts the interactive REPL mode.
+//
+// It wraps repl.RunREPL() and returns an error if the REPL fails to start.
 func runREPL() error {
 	if err := repl.RunREPL(); err != nil {
 		return fmt.Errorf("REPL error: %w", err)
@@ -63,13 +115,17 @@ func runREPL() error {
 	return nil
 }
 
-// runRPN parses and evaluates an RPN expression
+// runRPN parses and evaluates an RPN (Reverse Polish Notation) expression.
+//
+// It creates a fresh RPN calculator with fresh variable store for each call,
+// making it suitable for one-off calculations.
 func runRPN(input string) (string, error) {
 	vars := rpn.NewVariables()
 	rpnCalc := rpn.NewRPN(vars)
 	return rpnCalc.ParseAndEvaluate(input)
 }
 
+// printUsage displays the command-line usage information and examples.
 func printUsage() {
 	fmt.Println("Usage: gt <calculation>")
 	fmt.Println("       gt version")
-- 
cgit v1.2.3