Comments

closes #17
cc #89

Author: nrc

guide/guide.md

@@ -13,10 +13,73 @@ Use spaces, not tabs.
 ### [Statements](statements.md)
 ### [Expressions](expressions.md)
 
-### Doc comments
+
+### Comments
+
+The following guidelines are recommendations only, a mechanical formatter should
+not change comments except to move them within a file. To be clear this means
+changing the whitespace before a line comment or the whitespace before or after
+a block comment.
+
+Prefer line comments (`//`) to block comments (`/* ... */`).
+
+When using line comments there should be a single space the opening sigil.
+
+When using single-line block comments there should be a single space after the
+opening sigil and before the closing sigil. Multi-line block comments should
+have a newline after the opening sigil and before the closing sigil.
+
+Prefer to put a comment on its own line. Where a comment follows code, there
+should be a single space before it. Where a block comment is inline, there
+should be surrounding whitespace as if it were an identifier or keyword. There
+should be no trailing whitespace after a comment. Examples:
+
+```rust
+// A comment on an item.
+struct Foo { ... }
+
+fn foo() {} // A comment after an item.
+
+pub fn foo(/* a comment before an argument */ x: T) {...}
+```
+
+Comments should usually be complete sentences. Start with a capital letter, end
+with a period (`.`). An inline block comment may be treated as a note without
+punctuation.
+
+Source lines which are entirely a comment should be limited to 80 characters
+(including comment sigils) in length or the maximum width of the line, whichever
+is smaller:
+
+```rust
+// This comment is goes up to the .............................. 80 char margin.
+
+{
+    // This comment is .............................................. 80 chars wide.
+}
+
+{
+    {
+        {
+            {
+                {
+                    {
+                        // This comment is limited by the ......................... 100 char margin.
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+#### Doc comments
+
+Prefer line comments (`///`) to block comments (`//* ... */`).
 
 Prefer outer doc comments (`///` or `//*`), only use inner doc comments (`//!`
-and `/*!`) to write module-level documentation.
+and `//*!`) to write module-level or crate-level documentation.
+
 
 ### Attributes