Skip to content

Commit fc39a29

Browse files
Add disclaimer to protobuf grammar documentation.
The grammar is known incomplete, especially in terms of whitespace. Fixes protocolbuffers/protobuf#2128 PiperOrigin-RevId: 914817054
1 parent d4f393d commit fc39a29

4 files changed

Lines changed: 30 additions & 2 deletions

File tree

content/reference/protobuf/edition-2023-spec.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ description = "Language specification reference for edition 2023 of the Protocol
66
type = "docs"
77
+++
88

9+
**Note:** This language specification is known to be incomplete, particularly
10+
regarding whitespace handling and other lexical nuances. The C++ `protoc`
11+
compiler implementation serves as the definitive source of truth. This document
12+
is a best-effort attempt to describe the behavior of the handwritten parser,
13+
which is not based on a formal grammar.
14+
915
The syntax is specified using
1016
[Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form):
1117

content/reference/protobuf/edition-2024-spec.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ description = "Language specification reference for edition 2024 of the Protocol
66
type = "docs"
77
+++
88

9+
**Note:** This language specification is known to be incomplete, particularly
10+
regarding whitespace handling and other lexical nuances. The C++ `protoc`
11+
compiler implementation serves as the definitive source of truth. This document
12+
is a best-effort attempt to describe the behavior of the handwritten parser,
13+
which is not based on a formal grammar.
14+
915
The syntax is specified using
1016
[Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form):
1117

@@ -274,15 +280,19 @@ reserved foo, bar;
274280
Some message and enum definitions can be annotated to override their default
275281
symbol visibility.
276282

277-
This is controlled by [`features.default_symbol_visibility`](/editions/features/#symbol-vis) and symbol visibility is further documented in [export / local Keywords](/editions/overview/#export-local)
283+
This is controlled by
284+
[`features.default_symbol_visibility`](/editions/features/#symbol-vis)
285+
and symbol visibility is further documented in
286+
[export / local Keywords](/editions/overview/#export-local)
278287

279288
```
280289
symbolVisibility = "export" | "local"
281290
```
282291

283292
### Enum definition {#enum_definition}
284293

285-
The enum definition consists of a name and an enum body. The enum body can have options, enum fields, and reserved statements.
294+
The enum definition consists of a name and an enum body. The enum body can have
295+
options, enum fields, and reserved statements.
286296

287297
```
288298
enum = [ symbolVisibility ] "enum" enumName enumBody

content/reference/protobuf/proto2-spec.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ description = "Language specification reference for the proto2 syntax and its re
66
type = "docs"
77
+++
88

9+
**Note:** This language specification is known to be incomplete, particularly
10+
regarding whitespace handling and other lexical nuances. The C++ `protoc`
11+
compiler implementation serves as the definitive source of truth. This document
12+
is a best-effort attempt to describe the behavior of the handwritten parser,
13+
which is not based on a formal grammar.
14+
915
The syntax is specified using
1016
[Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form):
1117

content/reference/protobuf/proto3-spec.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@ description = "Language specification reference for the Protocol Buffers languag
66
type = "docs"
77
+++
88

9+
**Note:** This language specification is known to be incomplete, particularly
10+
regarding whitespace handling and other lexical nuances. The C++ `protoc`
11+
compiler implementation serves as the definitive source of truth. This document
12+
is a best-effort attempt to describe the behavior of the handwritten parser,
13+
which is not based on a formal grammar.
14+
915
The syntax is specified using
1016
[Extended Backus-Naur Form (EBNF)](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form):
1117

0 commit comments

Comments
 (0)