From 9ec051d3b37ccd7c89781f7319d58dce19f6fa23 Mon Sep 17 00:00:00 2001
From: Ergenekon Yigit <ergenekonyigit@hotmail.com>
Date: Thu, 28 Apr 2016 11:22:11 +0300
Subject: [PATCH] update comments RFC and code snippets

---
 src/doc/style/style/comments.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/doc/style/style/comments.md b/src/doc/style/style/comments.md
index bf8cf653dbb..af02d87cc8d 100644
--- a/src/doc/style/style/comments.md
+++ b/src/doc/style/style/comments.md
@@ -1,4 +1,4 @@
-% Comments [FIXME: needs RFC]
+% Comments [RFC #505]
 
 ### Avoid block comments.
 
@@ -74,7 +74,25 @@ For example:
 
 ### Code snippets
 
-> **[FIXME]**
+Only use inner doc comments `//!` to write crate and module-level documentation,
+nothing else. When using `mod` blocks, prefer `///` outside of the block:
+
+```rust
+/// This module contains tests
+mod test {
+    // ...
+}
+```
+
+over
+
+```rust
+mod test {
+    //! This module contains tests
+
+    // ...
+}
+```
 
 ### Avoid inner doc comments.