internal/encoding/pack: replace AST with CST in documentation
According to linguistics, this is actually a concrete syntax tree, rather
than an abstract syntax tree since it perfectly represents the grammatical
structure of the original raw input.
On the other hand, an abstract syntax tree (AST) loses some
grammatical structure and is only concerned with preserving syntax.
See https://eli.thegreenplace.net/2009/02/16/abstract-vs-concrete-syntax-trees/
Change-Id: Ia3fdb407d2b15c5431984956b7d74921891c2ad9
Reviewed-on: https://go-review.googlesource.com/133995
Reviewed-by: Herbie Ong <herbie@google.com>
diff --git a/internal/encoding/pack/pack.go b/internal/encoding/pack/pack.go
index 89601ba..aeb3390 100644
--- a/internal/encoding/pack/pack.go
+++ b/internal/encoding/pack/pack.go
@@ -52,7 +52,9 @@
type (
// Token is any other type (e.g., Message, Tag, Varint, Float32, etc).
Token token
- // Message is a ordered sequence Tokens.
+ // Message is an ordered sequence of Tokens, where certain tokens may
+ // contain other tokens. It is functionally a concrete syntax tree that
+ // losslessly represents any arbitrary wire data (including invalid input).
Message []Token
// Tag is a tuple of the field number and the wire type.
@@ -168,7 +170,7 @@
return n
}
-// Message encodes an AST into the protobuf wire format.
+// Message encodes a syntax tree into the protobuf wire format.
//
// Example message definition:
// message MyMessage {
@@ -242,12 +244,12 @@
return out
}
-// Unmarshal parses the input protobuf wire data as a Message AST.
+// Unmarshal parses the input protobuf wire data as a syntax tree.
// Any parsing error results in the remainder of the input being
// concatenated to the message as a Raw type.
//
// Each tag (a tuple of the field number and wire type) encountered is
-// appended to the AST as a Tag.
+// inserted into the syntax tree as a Tag.
//
// The contents of each wire type is mapped to the following Go types:
// VarintType => Uvarint
@@ -271,7 +273,7 @@
m.UnmarshalDescriptor(in, nil)
}
-// UnmarshalDescriptor parses the input protobuf wire data as a Message AST
+// UnmarshalDescriptor parses the input protobuf wire data as a syntax tree
// using the provided message descriptor for more accurate parsing of fields.
// It operates like Unmarshal, but may use a wider range of Go types to
// represent the wire data.
@@ -482,7 +484,7 @@
}
}
-// Format implements a custom formatter to visualize the Message AST.
+// Format implements a custom formatter to visualize the syntax tree.
// Using "%#v" formats the Message in Go source code.
func (m Message) Format(s fmt.State, r rune) {
switch r {
