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..e6f62d1
--- /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 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,
+}
+```
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
 }