sashakoshka/hopp
sashakoshka/hopp
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases Wiki Activity

design: Add comments to the language spec

Browse Source
This commit is contained in:
Sasha Koshka 2025-10-13 13:42:11 -04:00
parent b6e180f466
commit fbc55534f6
1 changed files with 13 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
design/pdl-language.md
View File

@ -52,6 +52,7 @@ structures. They are separated by whitespace.
| RBrace | `}` | A right curly brace. | RBrace | `}` | A right curly brace.
| LBracket | `[` | A left square bracket. | LBracket | `[` | A left square bracket.
| RBracket | `]` | A right square bracket. | RBracket | `]` | A right square bracket.
| Comment | `\/\/.*$` | A doc comment starting with a double-slash.
## Syntax ## 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 message name (Ident), and the message's root type. This is usually a table, but
can be anything. 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: 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 { M0000 Connect {
0000 Name String, 0000 Name String,
0001 Password String, 0001 Password String,
} }
// UserList is sent from the server to the client in response to a Connect
// message.
M0001 UserList { M0001 UserList {
0000 Users []User, 0000 Users []User,
} }
// User holds profile information about a single user.
User { User {
0000 Name String, 0000 Name String,
0001 Bio String, 0001 Bio String,
@ -99,7 +109,7 @@ Below is an EBNF description of the language.
<field> -> <key> <ident> <type> <field> -> <key> <ident> <type>
<type> -> <ident> <type> -> <ident>
| "[" "]" <type> | "[" "]" <type>
| "{" (<field> ",")* [<field>] "}" | "{" (<comment>* <field> ",")* [<comment>* <field>] "}"
<message> -> <method> <ident> <type> <message> -> <comment>* <method> <ident> <type>
<typedef> -> <ident> <type> <typedef> -> <comment>* <ident> <type>
``` ```