Fixed markdown error and enhanced code block for CommentsFormattingSt…

…yle.markdown

CommentsFormattingStyle.markdown

@@ -7,25 +7,33 @@ Appledoc extracts documentation from specially formatted comments, giving you fr
 
 Appledoc only handles multiple line comments if they start with slash and double star and end with standard star and slash:
 
-    /** Some comment */
+```objc
+/** Some comment */
+```
 
 Lines may optionally start with whitespace and a single star char and appledoc will ignore the prefix star, like this:
 
-    /** Star prefixed comment
-    * spreading over multiple 
-    * lines
-    */
+```objc
+/** Star prefixed comment
+* spreading over multiple 
+* lines
+*/
+```
       
 To make transition from headerdoc a bit simpler, appledoc also accepts headerdoc style multiline comments:
 
-    /*! Comment */
+```objc
+/*! Comment */
+```
 
 ## Single line comments:
 
 appledoc also handles single line comments that start with three slashes. Two or more single line comments in consequtive lines are grouped together into a single comment:
 
-    /// Single line comment spreading
-    /// over multiple lines
+```objc
+/// Single line comment spreading
+/// over multiple lines
+```
 
 #Laying out comments
 
@@ -36,60 +44,72 @@ Appledoc has been designed to keep comments in source code as readable as possib
 
 Paragraphs are simply any number of consecutive rows of text separated by one or more empty (or tab and space only) lines:
 
-    First paragraph.
-	 
-    Second paragraph with lot's of
-    text spread accross multiple lines.
-	 
-    And another paragraph.
+```
+First paragraph.
+ 
+Second paragraph with lot's of
+text spread accross multiple lines.
+ 
+And another paragraph.
+```
 
 The first paragraph of the comment is automatically used as short description and remaining as long description or discussion. You can change default behavior via command line switches.
 
 ##Unordered lists
 
 Unordered lists use -, + or * markers in front of each item:
 
-    - First item.
-    - Second item with lot's of text
-      spread across multiple lines.
-    - Third item.
+```
+- First item.
+- Second item with lot's of text
+  spread across multiple lines.
+- Third item.
+```
 
 The list must be delimited from surrounding paragraphs by empty lines at the top and bottom. You can nest lists by prefixing them with tabs or spaces like this:
 
-    - Item 1
-	  - Item 1.1
-	  - Item 1.2
-		- Item 1.2.1
-	  - Item 1.3
-    - Item 2
+```
+- Item 1
+  - Item 1.1
+  - Item 1.2
+	- Item 1.2.1
+  - Item 1.3
+- Item 2
+```
 
 Note that you can combine ordered and unordered lists when nesting.
 
 ##Ordered lists
 
 Ordered lists use a number followed by a dot as a marker in front of each item:
 
-    1. First item
-    2. Second item
+```
+1. First item
+2. Second item
+```
 
 Numbers don't need to be consequtive, you can even use the same number for all items; appledoc will simply number the items by their order. All rules for unordered lists also apply for ordered lists: separation with empty lines, nesting etc., so it won't be repeated here.
 
 ##Examples and code blocks
 
 If you want to mark a block of text as an example, simply prefix each line with a tab or 4 (or more) spaces. Appledoc will automatically convert consequtive blocks of prefixed lines into a single code block. Similar to lists and other paragraph blocks, example section needs to be delimited from preceding and following paragraph with an empty line:
 
-	Normal paragraph text
-		 
-		First line of example
-		Second line of example
-		 
-	Next paragraph.
+```
+Normal paragraph text
+	 
+	First line of example
+	Second line of example
+	 
+Next paragraph.
+```
 
 ##Important information blocks
 
 You mark a paragraph as important by prefixing it's first line with @warning directive. For example, this is how you can achieve effect Apple uses for these blocks:
 
-    @warning *Important:* Sending this message before `readValues:fromFile:` will result in unpredicted results, most likely as runtime exception!
+```
+@warning *Important:* Sending this message before `readValues:fromFile:` will result in unpredicted results, most likely as runtime exception!
+```
 
 *Important*: All text after `@warning` directive, up to next `"@"` directive will become part of the block - currently it's not possible to terminate warning block manually and continue with normal paragraphs! This allows you nesting lists and multiple paragraphs, but may come as surprise when not expected. Therefore it's recommended to use warning blocks at the end of "normal" paragraphs (and as any "@" directive will end previous block or paragraph, you can put them above method directives). Something to keep in mind!
 
@@ -136,8 +156,10 @@ Any valid URL address starting with `http://`, `https://`, `ftp://`, `file://` o
 
 Any word that matches known class, category or protocol name is automatically converted to cross reference link to that object. Assuming complete documentation contains class GBClass, it's extension GBClass(), category NSError(GBError) and protocol GBProtocol, the following text will automatically convert text:
 
-    This text contains links to: class GBClass, it's extension GBClass(), 
-    category NSError(GBError) and protocol GBProtocol.
+```
+This text contains links to: class GBClass, it's extension GBClass(), 
+category NSError(GBError) and protocol GBProtocol.
+```
 
 into something like:
 
@@ -147,9 +169,11 @@ This text contains links to: class [GBClass](http://), it's extension [GBClass()
 
 Any word that matches method or property selector name of "current" class, category or protocol is automatically converted to cross reference link to that member. Assuming current object contains method runWithValue:afterDelay: and property value, the following text:
 
-	This text contains links to:
-	method runWithValue:afterDelay: and
-	property value.
+```
+This text contains links to:
+method runWithValue:afterDelay: and
+property value.
+```
 
 will automatically convert to something like:
 
@@ -159,9 +183,11 @@ This text contains links to: method [runWithValue:afterDelay:](http://) and prop
 
 Creating cross reference links to members of other classes, categories or protocols requires a bit more effort as you need to state the class and the method, but still follows the same principle. Assuming complete documentation contains class GBClass which has method runWithValue:afterDelay: and property value, the following text:
 
-	This text contains links to:
-	method [GBClass runWithValue:afterDelay] and
-	property [GBClass value]
+```
+This text contains links to:
+method [GBClass runWithValue:afterDelay] and
+property [GBClass value]
+```
 
 will convert to something like:
 
@@ -171,14 +197,16 @@ This text contains links to: method [[GBClass runWithValue:afterDelay:](http://)
 
 As appledoc parses Markdown links for known objects, you can take advantage of link descriptions and even reference-type links to add that fine touch to generated documentation. For example:
 
-	For more info check [this page](http://gentlebytes.com), 
-	also take a look at [this class](GBClass) 
-	and [this method]([GBClass method:]).
+```
+For more info check [this page](http://gentlebytes.com), 
+also take a look at [this class](GBClass) 
+and [this method]([GBClass method:]).
 
-	For referring to common object multiple times,
-	use this [class][1]. And [repeat again][1].
+For referring to common object multiple times,
+use this [class][1]. And [repeat again][1].
 
-	[1] GBClass
+[1] GBClass
+```
 
 As long as `GBClass` and `[GBClass method:]` are recognized as valid cross references, the above example is converted to something like:
 
@@ -203,31 +231,39 @@ For methods and properties you may want to document their parameters, results or
 - **Generating related links**: `@see <name>` or `@sa <name>`. Although you can provide cross reference links anywhere within the paragraph text, as described above, you need to use @see directives to provide related context links for documentation sets. The name should follow cross reference guidelines described above.
 
   **Note**: Methods and properties keep all cross references in generated HTML, regardless of the referenced object. But when `@see` is used within class, category or protocol comment, only cross references to template documents are preserved and converted to companion guide links (generated in the table below the title). All other cross references - i.e. to other objects or members - are ignored. Oh, and remember, you can use nice descriptions using Markdown syntax, for example:
-
-      @see [String Programming Guide](document1).
+
+  ```
+  @see [String Programming Guide](document1).
+  ```
      
-* Grouping methods: `@name <title>`. All methods and properties declared after @name directive will be stored into a group with the given title. These groups are then extracted as tasks in generated HTML. Important: @name must be specified in it's own separate comment preceeding the first group method or property comment for which the task is specified! So this would work:
+- **Grouping methods**: `@name <title>`. All methods and properties declared after @name directive will be stored into a group with the given title. These groups are then extracted as tasks in generated HTML. Important: @name must be specified in it's own separate comment preceeding the first group method or property comment for which the task is specified! So this would work:
+
+  ```objc
+  /** @name Section title */
 
-   	  /** @name Section title */
-
-	  /** Method description */
-	  - (void)someMethod;
+  /** Method description */
+  - (void)someMethod;
+  ```
 	  
   and this wouldn't:
 
-	  /** @name Section title
-
-      Method description */
-      - (void)someMethod;
+  ```objc
+  /** @name Section title
+
+  Method description */
+  - (void)someMethod;
+  ```
       
-* **Comment delimiters**: Any comment may optionally include delimiter lines. A delimiter line is any combination of 3 or more chars from the following set: `"!@#$%^&*()_=``~,<.>/?;:'\\"-"`. Such lines are ignored, so given a comment like this:
+- **Comment delimiters**: Any comment may optionally include delimiter lines. A delimiter line is any combination of 3 or more chars from the following set: `"!@#$%^&*()_=``~,<.>/?;:'\\"-"`. Such lines are ignored, so given a comment like this:
 
-   	  /// ---------------------------------
-	  /// comment
-	  /// ---------------------------------
+  ```objc
+  /// ---------------------------------
+  /// comment
+  /// ---------------------------------
+  ```
 
   will automatically strip first and last line. This is mostly used for making `@name` sections more stand out.
 
-* **Directives prefix**: Although all directives in examples above use "@" sign as a prefix, you can actually use any non-whitespace char instead, for example `\param`, `$param`, `%param` and so on...
+- **Directives prefix**: Although all directives in examples above use "@" sign as a prefix, you can actually use any non-whitespace char instead, for example `\param`, `$param`, `%param` and so on...
 
-And last, but not least, as appledoc uses standard Markdown rules, take a look at [Markdown documentation](http://daringfireball.net/projects/markdown/) and [Discount library ](http://www.pell.portland.or.us/~orc/Code/discount/)for more details and possibilities. This doc is only meant as a quick guide to general formatting and all appledoc specifics, not as comprehensive documentation of all supported Markdown features. Also take a look at [appledoc source code](https://github.com/tomaz/appledoc/) for examples of how it fits together.
+And last, but not least, as appledoc uses standard Markdown rules, take a look at [Markdown documentation](http://daringfireball.net/projects/markdown/) and [Discount library ](http://www.pell.portland.or.us/~orc/Code/discount/)for more details and possibilities. This doc is only meant as a quick guide to general formatting and all appledoc specifics, not as comprehensive documentation of all supported Markdown features. Also take a look at [appledoc source code](https://github.com/tomaz/appledoc/) for examples of how it fits together.