onevcat/VVDocumenter-Xcode — pull request #18 by idpaterson (2013-10-09 13:26:18+00:00)
Title: Option to prefix with slashes

I have always used three slashes as a prefix for appledoc documentation and thought it might be a useful option to add to this project. The pull request adds a new `prefixWithSlashes` option. The settings screen now shows a matrix of radio buttons allowing the user to choose between the 3 prefix options. The slashes option is disabled when HeaderDoc comments are enabled, since it is only supported by Appledoc.

![New prefix options](https://f.cloud.github.com/assets/507058/1297343/ed8fe9b2-30df-11e3-9893-fea6793e352e.png)

One caveat to using `///` for comments is that the `///` keyword causes issues when adding new lines to the comment. I would try to add a second line to the description but the plugin picked up the `///` trigger and inserted a second copy of the documentation block. I had to add some logic to avoid generating the comment if the previous or next lines in the editor are `///` documentation comments.

I hope this is useful, please let me know if anything needs to be fixed before the change can be merged.

### Why `///` instead of stars or whitespace?

If anyone is wondering why I use `///`, the reason is fairly simple, it's more reliable in Appledoc. Consider the following documentation that contains example code. In Appledoc, example code is simply indented 4 or more spaces.
```objc
/// This method does something very useful.
///
/// The following example shows an appropriate use of `doSomething`
///
/// NSLog(@"%@", thing.someProperty); // Logs "A"
/// [thing doSomething];
/// NSLog(@"%@", thing.someProperty); // Logs "B"
- (void)doSomething;
```
This generates the following in Appledoc, looks pretty good.
> ![Documentation example with 3 slashes](https://f.cloud.github.com/assets/507058/1297526/3e349508-30e4-11e3-9fa2-d5f973253219.png)

-----

However, if we try the same code with star-prefixed comments the result is much different. This is probably a bug in Appledoc, but it has been around for a long time. Examples are simply not picked up when a star prefix is used.
```objc
/**
* This method does something very useful.
*
* The following example shows an appropriate use of `doSomething`
*
* NSLog(@"%@", thing.someProperty); // Logs "A"
* [thing doSomething];
* NSLog(@"%@", thing.someProperty); // Logs "B"
*/
- (void)doSomething;
```
> ![Documentation example with star prefix](https://f.cloud.github.com/assets/507058/1297531/869c8e2c-30e4-11e3-948a-111c3fd79b12.png)

-----

It may seem to work fine without the star prefix.
```objc
/**
This method does something very useful.

The following example shows an appropriate use of `doSomething`

NSLog(@"%@", thing.someProperty); // Logs "A"
[thing doSomething];
NSLog(@"%@", thing.someProperty); // Logs "B"
*/
```
> ![Documentation with whitespace prefix](https://f.cloud.github.com/assets/507058/1297551/e515f114-30e4-11e3-8496-600effe73811.png)

-----

However, Appledoc does not have a concept of a base indentation level within a comment. If any line in this comment format is 4 or more spaces from the left it will be rendered as an example block. Yikes!
```objc
/**
This method does something very useful.

The following example shows an appropriate use of `doSomething`

NSLog(@"%@", thing.someProperty); // Logs "A"
[thing doSomething];
NSLog(@"%@", thing.someProperty); // Logs "B"
*/
- (void)doSomething;
```
> ![Documentation with indented whitespace prefix](https://f.cloud.github.com/assets/507058/1297585/3896d754-30e5-11e3-9ec4-770f4fc9cd47.png)