Update Comments documentation with preferred comment style (#40)

Update Comments.md to include details for the preferred comment style and example usages.

Comments.md

@@ -124,3 +124,61 @@ func loadLastCheckpoint() -> GameState? {
     return loadedState
 }
 ```
+
+## Convention: Single line and multi line comment types
+
+Single line and multi line comments in Swift can be written in a few different forms, some of which enable additional features such as markdown to provide richer documentation.
+
+## Rationale
+
+The triple slash style comment, `///`, is preferred for both single line and multi line comments as it allows for the use of markdown inside comments, provides automcomplete and quick help documentation, and is the default for Xcode's docmentation generation. Additional details about the different comment styles can be found in the [official documentation](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1).
+
+## Examples
+
+### Bad: single line comment without markdown used for public property description
+
+``` swift
+class SomeToolbar: UIView {
+    // Array holding UIViews shown inside toolbar
+    public var toolbarItems: [UIView]?
+}
+```
+
+### Good: single line comment with markdown used for public property description
+
+``` swift
+class SomeToolbar: UIView {
+    /// Array holding `UIView`s shown inside toolbar
+    public var toolbarItems: [UIView]?
+}
+```
+
+### Bad: multi-line comment without '///' style comment used for public method description
+
+``` swift
+class SomeToolbar: UIView {
+    /*
+     Hides the toolbar view.
+    
+     @param animated: When true, the view will hide with animation
+     @param completion: Block called after the view is finished hiding
+    */
+    public func hideToolbar(_ animated: Bool, completion: ((Bool) -> Void)?) {
+        setHidden(true, animated: animated, completion: completion)
+    }
+}
+```
+
+### Good: multi-line comment with `///` style comment used for public method description
+
+``` swift
+class SomeToolbar: UIView {
+    /// Hides the toolbar view.
+    ///
+    /// Parameter animated: When true, the view will hide with animation
+    /// Parameter completion: Block called after the view is finished hiding
+    public func hideToolbar(_ animated: Bool, completion: ((Bool) -> Void)?) {
+        setHidden(true, animated: animated, completion: completion)
+    }
+}
+```