From 6e9954681f916beb1ed342e41e650ebb0d350559 Mon Sep 17 00:00:00 2001
From: Jason Lee <huacnlee@gmail.com>
Date: Mon, 9 Jan 2023 20:18:33 +0800
Subject: [PATCH 1/2] Add doc for comments

---
 src/SUMMARY.md           |  1 +
 src/grammars/comments.md | 40 ++++++++++++++++++++++++++++++++++++++++
 src/grammars/syntax.md   |  2 ++
 3 files changed, 43 insertions(+)
 create mode 100644 src/grammars/comments.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 2310235..758e6e3 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -7,6 +7,7 @@
 - [Grammars](grammars/grammars.md)
     - [Parsing expression grammars](grammars/peg.md)
     - [Syntax of pest parsers](grammars/syntax.md)
+    - [Comments](grammars/comments.md)
     - [Built-in rules](grammars/built-ins.md)
     - [Example: JSON](examples/json.md)
     - [Example: The J language](examples/jlang.md)
diff --git a/src/grammars/comments.md b/src/grammars/comments.md
new file mode 100644
index 0000000..1fd496c
--- /dev/null
+++ b/src/grammars/comments.md
@@ -0,0 +1,40 @@
+## Comments
+
+### Non-doc comments
+
+Comments follow the general Rust style of line (`//`) and block (`/* ... */`) comment forms.
+Non-doc comments are interpreted as a form of whitespace.
+
+```pest
+/* 
+  Block comment
+ */
+another_rule = {        // line comment
+    ...                 // whitespace goes anywhere
+}
+```
+
+### Doc comments
+
+Line doc comments beginning with exactly three slashes `///`.
+And `//!` for document the entire of grammar file.
+
+```pest
+//! A parser for JSON file.
+
+json = { ... }
+
+/// Matches object, e.g.: `{ "foo": "bar" }`
+object = { ... }
+```
+
+Then will get
+
+```rust
+/// A parser for JSON file.
+enum Rule {
+    json,
+    /// Matches object, e.g.: `{ "foo": "bar" }`
+    object,
+}
+```
diff --git a/src/grammars/syntax.md b/src/grammars/syntax.md
index 3dd79d3..7e77227 100644
--- a/src/grammars/syntax.md
+++ b/src/grammars/syntax.md
@@ -3,8 +3,10 @@
 `pest` grammars are lists of rules. Rules are defined like this:
 
 ```pest
+//! Grammar doc
 my_rule = { ... }
 
+/// Rule doc
 another_rule = {        // comments are preceded by two slashes
     ...                 // whitespace goes anywhere
 }

From 050c0d5b675928960635aefed316c7cb6c5d029a Mon Sep 17 00:00:00 2001
From: Tomas Tauber <2410580+tomtau@users.noreply.github.com>
Date: Sun, 29 Jan 2023 09:47:41 +0800
Subject: [PATCH 2/2] Update src/grammars/comments.md

---
 src/grammars/comments.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/grammars/comments.md b/src/grammars/comments.md
index 1fd496c..e6f62d1 100644
--- a/src/grammars/comments.md
+++ b/src/grammars/comments.md
@@ -16,8 +16,8 @@ another_rule = {        // line comment
 
 ### Doc comments
 
-Line doc comments beginning with exactly three slashes `///`.
-And `//!` for document the entire of grammar file.
+Line doc comments begin with exactly three slashes `///`
+ and `//!` is used to document the entire grammar file.
 
 ```pest
 //! A parser for JSON file.