update comments RFC and code snippets

1 files 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.