generate: Add comments to protocol data structures, tests

generate/generate.go

@@ -112,8 +112,11 @@ func (this *Generator) Generate(protocol *Protocol) (n int, err error) {
 	return n, nil
 }
 
-func (this *Generator) generateTypedef(name string, typ Type) (n int, err error) {
+func (this *Generator) generateTypedef(name string, typedef Typedef) (n int, err error) {
+	typ := typedef.Type
+
 	// type definition
+	// TODO doc
 	nn, err := this.iprintf(
 		"\n// %s represents the protocol data type %s.\n",
 		name, name)
@@ -208,6 +211,7 @@ func (this *Generator) generateTypedef(name string, typ Type) (n int, err error)
 // generateMessage generates the structure, as well as encoding decoding
 // functions for the given message.
 func (this *Generator) generateMessage(method uint16, message Message) (n int, err error) {
+	// TODO doc
 	nn, err := this.iprintf(
 		"\n// %s represents the protocol message M%04X %s.\n",
 		message.Name, method, message.Name)
@@ -1090,6 +1094,7 @@ func (this *Generator) generateTypeTableDefined(typ TypeTableDefined) (n int, er
 
 	for _, key := range slices.Sorted(maps.Keys(typ.Fields)) {
 		field := typ.Fields[key]
+		// TODO doc
 		nn, err := this.iprintf("%s ", field.Name)
 		n += nn; if err != nil { return n, err }
 		nn, err = this.generateType(field.Type)
@@ -1180,12 +1185,12 @@ func (this *Generator) resolveMessageName(message string) string {
 }
 
 func (this *Generator) resolveTypeName(name string) (Type, error) {	
-	if typ, ok := this.protocol.Types[name]; ok {
+	if typedef, ok := this.protocol.Types[name]; ok {
-		if typ, ok := typ.(TypeNamed); ok {
+		if typ, ok := typedef.Type.(TypeNamed); ok {
 			return this.resolveTypeName(typ.Name)
 		}
 		
-		return typ, nil
+		return typedef.Type, nil
 	}
 	return nil, fmt.Errorf("no type exists called %s", name)
 }

generate/generate_test.go

@@ -83,11 +83,13 @@ func init() {
 			},
 		},
 	}
-	exampleProtocol.Types["User"] = TypeTableDefined {
+	exampleProtocol.Types["User"] = Typedef {
-		Fields: map[uint16] Field {
+		Type: TypeTableDefined {
-			0x0000: Field { Name: "Name",      Type: TypeString { } },
+			Fields: map[uint16] Field {
-			0x0001: Field { Name: "Bio",       Type: TypeString { } },
+				0x0000: Field { Name: "Name",      Type: TypeString { } },
-			0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
+				0x0001: Field { Name: "Bio",       Type: TypeString { } },
+				0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
+			},
 		},
 	}
 }

generate/parse.go

@@ -21,7 +21,7 @@ func Parse(lx parse.Lexer) (*Protocol, error) {
 func defaultProtocol() Protocol {
 	return Protocol {
 		Messages: make(map[uint16] Message),
-		Types: map[string] Type { },
+		Types: map[string] Typedef { },
 	}
 }
 
@@ -72,6 +72,7 @@ func (this *parser) parseMessage() error {
 	if err != nil { return err }
 	this.protocol.Messages[uint16(method)] = Message {
 		Name: name,
+		// TODO: doc
 		Type: typ,
 	}
 	return nil
@@ -85,7 +86,10 @@ func (this *parser) parseTypedef() error {
 	if err != nil { return err }
 	typ, err := this.parseType()
 	if err != nil { return err }
-	this.protocol.Types[name] = typ
+	this.protocol.Types[name] = Typedef {
+		// TODO: doc
+		Type: typ,
+	}
 	return nil
 }
 
@@ -192,6 +196,7 @@ func (this *parser) parseField() (uint16, Field, error) {
 	if err != nil { return 0, Field { }, err }
 	return uint16(key), Field {
 		Name: name,
+		// TODO: doc
 		Type: typ,
 	}, nil
 }

generate/parse_test.go

@@ -9,6 +9,7 @@ func TestParse(test *testing.T) {
 	correct := defaultProtocol()
 	correct.Messages[0x0000] = Message {
 		Name: "Connect",
+		Doc:  "Connect is sent from the client to the server as the first message of an\n authenticated transaction.",
 		Type: TypeTableDefined {
 			Fields: map[uint16] Field {
 				0x0000: Field { Name: "Name",      Type: TypeString { } },
@@ -18,32 +19,44 @@ func TestParse(test *testing.T) {
 	}
 	correct.Messages[0x0001] = Message {
 		Name: "UserList",
+		Doc:  "UserList is sent from the server to the client in response to a Connect\nmessage.",
 		Type: TypeTableDefined {
 			Fields: map[uint16] Field {
 				0x0000: Field { Name: "Users",  Type: TypeArray { Element: TypeNamed { Name: "User" } } },
 			},
 		},
 	}
-	correct.Types["User"] = TypeTableDefined {
+	correct.Types["User"] = Typedef {
-		Fields: map[uint16] Field {
+		Doc:  "User holds profile information about a single user.",
-			0x0000: Field { Name: "Name",      Type: TypeString { } },
+		Type: TypeTableDefined {
-			0x0001: Field { Name: "Bio",       Type: TypeString { } },
+			Fields: map[uint16] Field {
-			0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
+				0x0000: Field { Name: "Name",      Type: TypeString { } },
+				0x0001: Field { Name: "Bio",       Type: TypeString { } },
+				0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
+			},
 		},
 	}
-	correct.Types["Anything"] = TypeAny { }
+	correct.Types["Anything"] = Typedef {
+		Type: TypeAny { },
+	}
 	test.Log("CORRECT:", &correct)
 	
 	got, err := ParseReader("test.pdl", strings.NewReader(`
+	// Connect is sent from the client to the server as the first message of an
+	// authenticated transaction.
 	M0000 Connect {
 		0000 Name String,
+		// Password is where you put your secrets, your shameful secrets
 		0001 Password String,
 	}
 	
+	// UserList is sent from the server to the client in response to a Connect
+	// message.
 	M0001 UserList {
 		0000 Users []User,
 	}
 	
+	// User holds profile information about a single user.
 	User {
 		0000 Name      String,
 		0001 Bio       String,

generate/protocol.go

@@ -7,11 +7,17 @@ import "crypto/md5"
 
 type Protocol struct {
 	Messages map[uint16] Message
-	Types    map[string] Type
+	Types    map[string] Typedef
 }
 
 type Message struct {
 	Name string
+	Doc  string
+	Type Type
+}
+
+type Typedef struct {
+	Doc  string
 	Type Type
 }
 
@@ -84,6 +90,7 @@ func (typ TypeTableDefined) String() string {
 
 type Field struct {
 	Name string
+	Doc  string
 	Type Type
 }