Add doc for comments

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)

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 begin with exactly three slashes `///`
+ and `//!` is used to document the entire 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,
+}
+```

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
 }