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 typ, ok := typ.(TypeNamed); ok {
+	if typedef, ok := this.protocol.Types[name]; 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,12 +83,14 @@ func init() {
 			},
 		},
 	}
-	exampleProtocol.Types["User"] = TypeTableDefined {
+	exampleProtocol.Types["User"] = Typedef {
+		Type: TypeTableDefined {
 			Fields: map[uint16] Field {
 				0x0000: Field { Name: "Name",      Type: TypeString { } },
 				0x0001: Field { Name: "Bio",       Type: TypeString { } },
 				0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
 			},
+		},
 	}
 }
 

generate/lex.go

@@ -15,6 +15,7 @@ const (
 	TokenRBrace
 	TokenLBracket
 	TokenRBracket
+	TokenComment
 )
 
 var tokenNames = map[parse.TokenKind] string {
@@ -26,6 +27,7 @@ var tokenNames = map[parse.TokenKind] string {
 	TokenRBrace:   "RBrace",
 	TokenLBracket: "LBracket",
 	TokenRBracket: "RBracket",
+	TokenComment:  "Comment",
 }
 
 func Lex(fileName string, reader io.Reader) (parse.Lexer, error) {
@@ -81,6 +83,18 @@ func (this *lexer) nextInternal() (token parse.Token, err error) {
 		}
 	}
 
+	unexpected := func() error {
+		if unicode.IsPrint(this.rune) {
+			return parse.Errorf (
+				this.pos(), "unexpected rune '%c'",
+				this.rune)
+		} else {
+			return parse.Errorf (
+				this.pos(), "unexpected rune %U",
+				this.rune)
+		}
+	}
+
 	defer func () {
 		newPos := this.pos()
 		newPos.End -- // TODO figure out why tf we have to do this
@@ -133,14 +147,21 @@ func (this *lexer) nextInternal() (token parse.Token, err error) {
 		token.Kind = TokenRBracket
 		appendRune()
 		if this.eof { err = nil; return }
-	case unicode.IsPrint(this.rune):
-		err = parse.Errorf (
-			this.pos(), "unexpected rune '%c'",
-			this.rune)
+	// Comment
+	case this.rune == '/':
+		token.Kind = TokenComment
+		appendRune()
+		if this.eof { return }
+		if this.rune != '/' {
+			err = unexpected()
+			return
+		}
+		for this.rune != '\n' {
+			appendRune()
+			if this.eof { err = nil; return }
+		}
 	default:
-		err = parse.Errorf (
-			this.pos(), "unexpected rune %U",
-			this.rune)
+		err = unexpected()
 	}
 
 	return

generate/lex_test.go

@@ -6,14 +6,21 @@ import "git.tebibyte.media/sashakoshka/goparse"
 
 func TestLex(test *testing.T) {
 	lexer, err := Lex("test.pdl", strings.NewReader(`
+	// User holds profile information about a single user.
 	M0001 User {
 		0000 Name      String,
+		// dog water comment
+		
+		// Users is asdkjsagkj why
+		// 
+		// wow
 		0001 Users []User,
 		0002 Followers U32,
 	}`))
 	if err != nil { test.Fatal(parse.Format(err)) }
 
 	correctTokens := []parse.Token {
+		tok(TokenComment,  "// User holds profile information about a single user."),
 		tok(TokenMethod,   "0001"),
 		tok(TokenIdent,    "User"),
 		tok(TokenLBrace,   "{"),
@@ -21,6 +28,10 @@ func TestLex(test *testing.T) {
 		tok(TokenIdent,    "Name"),
 		tok(TokenIdent,    "String"),
 		tok(TokenComma,    ","),
+		tok(TokenComment,  "// dog water comment"),
+		tok(TokenComment,  "// Users is asdkjsagkj why"),
+		tok(TokenComment,  "// "),
+		tok(TokenComment,  "// wow"),
 		tok(TokenKey,      "0001"),
 		tok(TokenIdent,    "Users"),
 		tok(TokenLBracket, "["),

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 {
+		Doc:  "User holds profile information about a single user.",
+		Type: TypeTableDefined {
 			Fields: map[uint16] Field {
 				0x0000: Field { Name: "Name",      Type: TypeString { } },
 				0x0001: Field { Name: "Bio",       Type: TypeString { } },
 				0x0002: Field { Name: "Followers", Type: TypeInt { Bits: 32 } },
 			},
+		},
+	}
+	correct.Types["Anything"] = Typedef {
+		Type: TypeAny { },
 	}
-	correct.Types["Anything"] = 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
 }