Add godoc comments

Author: hjr265

ast/ast.go

@@ -1,3 +1,4 @@
+// Package ast defines the abstract syntax tree for the Scanspec language.
 package ast
 
 import (
@@ -6,10 +7,12 @@ import (
     "github.com/alecthomas/participle/v2/lexer"
 )
 
+// Node is the interface implemented by all AST nodes.
 type Node interface {
     node()
 }
 
+// Source is the root node of a Scanspec AST.
 type Source struct {
     Block Block `@@`
 }

ast/parse.go

@@ -22,6 +22,7 @@ var parser = participle.MustBuild[Source](participle.Lexer(lexer.MustSimple([]le
 	participle.UseLookahead(2),
 )
 
+// ParseString parses a Scanspec source string and returns the AST.
 func ParseString(filename string, s string) (*Source, error) {
 	n, err := parser.ParseString(filename, s)
 	if err != nil {

ast/walk.go

@@ -2,10 +2,14 @@ package ast
 
 import "fmt"
 
+// Visitor defines the interface for AST visitors. If Visit returns a
+// non-nil Visitor, Walk recurses into the node's children with that visitor.
 type Visitor interface {
     Visit(Node) Visitor
 }
 
+// Walk traverses an AST in depth-first order. It calls v.Visit(n), and if that
+// returns a non-nil visitor, it recursively walks each child of n.
 func Walk(v Visitor, n Node) {
     v = v.Visit(n)
     if v == nil {
@@ -198,6 +202,8 @@ func (f inspector) Visit(node Node) Visitor {
     return nil
 }
 
+// Inspect traverses an AST, calling f for each node. If f returns false,
+// Inspect does not recurse into the node's children.
 func Inspect(node Node, f func(Node) bool) {
     Walk(inspector(f), node)
 }

eval/builtin.go

@@ -7,6 +7,7 @@ import (
 	"strconv"
 )
 
+// Functions maps built-in function names to their implementations.
 var Functions = map[string]func(args ...interface{}) (interface{}, error){
 	"len": func(args ...interface{}) (interface{}, error) {
 		s, ok := args[0].(string)

eval/error.go

@@ -144,6 +144,7 @@ func (e ErrBadParse) Error() string {
 	return fmt.Sprintf("%d:%d~%d:%d: parse error: want %s, got %q", e.Pos.Line, e.Pos.Column, e.Cursor.Ln, e.Cursor.Col, e.Want, e.Got)
 }
 
+// Cursor represents a position in the input stream.
 type Cursor struct {
 	Ln, Col int
 }

eval/evaluator.go

@@ -1,3 +1,5 @@
+// Package eval evaluates a Scanspec AST against input data, scanning values
+// and validating constraints.
 package eval
 
 import (
@@ -17,6 +19,8 @@ type evaluator struct {
 	Values Values
 }
 
+// Evaluate executes a Scanspec AST against the provided input, returning the
+// scanned values or an error if a constraint check fails or parsing fails.
 func Evaluate(source *ast.Source, input io.Reader, options ...Option) (values Values, err error) {
 	e := evaluator{
 		Source: source,

eval/option.go

@@ -1,5 +1,6 @@
 package eval
 
+// Option configures the evaluator.
 type Option interface {
 	apply(*evaluator)
 }
@@ -10,6 +11,8 @@ func (f optionFunc) apply(e *evaluator) {
 	f(e)
 }
 
+// ScannerBuffer returns an Option that sets the initial buffer and maximum
+// buffer size for the input scanner.
 func ScannerBuffer(buf []byte, max int) Option {
 	return optionFunc(func(e *evaluator) {
 		e.Input.sc.Buffer(buf, max)

eval/type.go

@@ -2,6 +2,7 @@ package eval
 
 import "reflect"
 
+// Types maps Scanspec type names to their Go reflect.Type equivalents.
 var Types = map[string]reflect.Type{
 	"bool":    reflect.TypeOf(bool(false)),
 	"int":     reflect.TypeOf(int(0)),
@@ -11,4 +12,5 @@ var Types = map[string]reflect.Type{
 	"string":  reflect.TypeOf(string("")),
 }
 
+// Values holds the scanned variable values, keyed by variable name.
 type Values map[string]reflect.Value

gen/c99/c.go

@@ -1,5 +1,6 @@
 // Copyright 2020 Furqan Software Ltd. All rights reserved.
 
+// Package c99 generates C99 source code from a Scanspec AST.
 package c99
 
 import (
@@ -13,11 +14,14 @@ import (
 	"git.furqansoftware.net/toph/scanlib/gen/code"
 )
 
+// Generator walks a Scanspec AST and emits C99 source code.
 type Generator struct {
 	ctx *Context
 	err error
 }
 
+// Generate generates C99 source code from a Scanspec AST. It returns
+// [gen.ErrUnsupportedType] if the Scanspec uses the string type.
 func Generate(n *ast.Source) ([]byte, error) {
 	ctx := Context{
 		types:    map[string]string{},

gen/code/writer.go

@@ -1,5 +1,6 @@
 // Copyright 2020 Furqan Software Ltd. All rights reserved.
 
+// Package code provides utilities for code generation.
 package code
 
 import (
@@ -8,6 +9,7 @@ import (
 	"strings"
 )
 
+// Writer is an indentation-aware code writer.
 type Writer struct {
 	buf *bytes.Buffer
 
@@ -17,6 +19,8 @@ type Writer struct {
 	r, c int
 }
 
+// NewWriter returns a new Writer that uses the given string for each
+// indentation level.
 func NewWriter(indent string) *Writer {
 	return &Writer{
 		buf:    &bytes.Buffer{},