From fbc55534f6ec153f66e49760cf981220eb804ee0 Mon Sep 17 00:00:00 2001
From: Sasha Koshka <sashakoshka@tebibyte.media>
Date: Mon, 13 Oct 2025 13:42:11 -0400
Subject: [PATCH] design: Add comments to the language spec

---
 design/pdl-language.md | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/design/pdl-language.md b/design/pdl-language.md
index ba77e4a..914ea6a 100644
--- a/design/pdl-language.md
+++ b/design/pdl-language.md
@@ -52,6 +52,7 @@ structures. They are separated by whitespace.
 | RBrace   | `}`                | A right curly brace.
 | LBracket | `[`                | A left square bracket.
 | RBracket | `]`                | A right square bracket.
+| Comment  | `\/\/.*$`          | A doc comment starting with a double-slash.
 
 ## Syntax
 
@@ -68,18 +69,27 @@ an Ident token respectively. A message consists of the method code (Method), the
 message name (Ident), and the message's root type. This is usually a table, but
 can be anything.
 
+Messages, types, and table fields can all have doc comments preceding them,
+which are used to generate documentation for the protocol. The syntax is the
+same as Go's (for now). Comments aren't allowed anywhere else.
+
 Here is an example of all that:
 
 ```
+// Connect is sent from the client to the server as the first message of an
+// authenticated transaction.
 M0000 Connect {
 	0000 Name String,
 	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,
@@ -99,7 +109,7 @@ Below is an EBNF description of the language.
 <field>   -> <key> <ident> <type>
 <type> -> <ident>
         | "[" "]" <type>
-        | "{" (<field> ",")* [<field>] "}"
-<message> -> <method> <ident> <type>
-<typedef> -> <ident> <type>
+        | "{" (<comment>* <field> ",")* [<comment>* <field>] "}"
+<message> -> <comment>* <method> <ident> <type>
+<typedef> -> <comment>* <ident> <type>
 ```