From 1d332cd112fe1c89ddb7ff2f86698a2aa50dc4a9 Mon Sep 17 00:00:00 2001
From: Thomas Pelletier <pelletier.thomas@gmail.com>
Date: Thu, 25 Mar 2021 20:46:31 -0400
Subject: [PATCH] Add documentation for the AST

---
 internal/ast/ast.go | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/internal/ast/ast.go b/internal/ast/ast.go
index d565226..ba2729e 100644
--- a/internal/ast/ast.go
+++ b/internal/ast/ast.go
@@ -33,10 +33,14 @@ func (c *Iterator) Node() Node {
 	return c.node
 }
 
+// Root contains a full AST.
+//
+// It is immutable once constructed with Builder.
 type Root struct {
 	nodes []Node
 }
 
+// Iterator over the top level nodes.
 func (r *Root) Iterator() Iterator {
 	it := Iterator{}
 	if len(r.nodes) > 0 {
@@ -45,10 +49,6 @@ func (r *Root) Iterator() Iterator {
 	return it
 }
 
-func (r *Root) Reset() {
-	r.nodes = r.nodes[:0]
-}
-
 func (r *Root) at(idx int) Node {
 	// TODO: unsafe to point to the node directly
 	return r.nodes[idx]
@@ -77,7 +77,7 @@ type Node struct {
 // next node.
 func (n Node) Next() Node {
 	if n.next <= 0 {
-		return NoNode
+		return noNode
 	}
 	return n.root.at(n.next)
 }
@@ -87,16 +87,17 @@ func (n Node) Next() Node {
 // Returns an invalid Node if there is none.
 func (n Node) Child() Node {
 	if n.child <= 0 {
-		return NoNode
+		return noNode
 	}
 	return n.root.at(n.child)
 }
 
+// Valid returns true if the node's kind is set (not to Invalid).
 func (n Node) Valid() bool {
 	return n.Kind != Invalid
 }
 
-var NoNode = Node{}
+var noNode = Node{}
 
 // Key returns the child nodes making the Key on a supported node. Panics
 // otherwise.
@@ -125,6 +126,7 @@ func (n Node) Value() Node {
 	return n.Child()
 }
 
+// Children returns an iterator over a node's children.
 func (n Node) Children() Iterator {
 	return Iterator{node: n.Child()}
 }