tomaz/appledoc — pull request #421 by idpaterson (2014-01-09 17:21:14+00:00)
Title: Grouping for indented single line comments

Allows single-line comments spanning multiple lines to be grouped if they have the same indentation.

I have always used single-line comments because historically it has been less prone to [issues like these](https://github.com/onevcat/VVDocumenter-Xcode/pull/18) in Xcode and Appledoc. However, I noticed when documenting enums or any other code that is commonly indented such as ivars that only the last line of each comment block was included in documentation.

In the following example, due to the indentation of the comments under each enum value, the comments were not being grouped. This resulted in the documentation for `NTXUIWebViewUnknownState` reading simply `cannot yet be determined.` with a similar problem affecting the other comments that fill multiple lines.
```objc
/// A representation of the DOM `readyState` for the current request in a web
/// view. Implementation of this state allows inspection of the web view
/// progress at a much more meaningful level than is provided in the
/// `UIWebViewDelegate`.
typedef NS_ENUM(NSUInteger, NTXUIWebViewReadyState)
{
/// The web view has not been yet been populated with a request, or the state
/// cannot yet be determined.
NTXUIWebViewUnknownState,
/// A request is still pending for the document. At this time the web view is
/// still displaying the previous document.
NTXUIWebViewUninitializedState,
/// The document has started to load but is not yet fully loaded and parsed.
NTXUIWebViewLoadingState,
/// The document has been loaded and parsed, the web view is ready to receive
/// input such as JS commands, but there are still some resources that have
/// not finished loading.
NTXUIWebViewInteractiveState,
/// The document and all dependent resources have finished loading.
NTXUIWebViewCompleteState
};
```

#### Implementation

This pull request addresses that issue by allowing consecutive single-line comments to be grouped if they have the same indentation. The indentation is determined by finding the index at the start of the line containing the comment, then testing for any non-whitespace characters in the original input between the start of the line and the start of the comment. If there are any non-whitespace characters, the comment is considered to have no indentation and cannot be grouped (though this seems to have already been the case). Otherwise, the indentation is considered to be the number of whitespace characters between the start of the line and the offset of the comment.

Private helper methods have been added for determining the start offset of the line containing any given offset, as well as to determine the indentation of any particular offset as defined by the rules above.

#### Tests

Two new tests are introduced to ensure that single-line comments with matching indentation are grouped and that those with mismatched indentation are not grouped. All tests pass.

#### Caveats

Spaces and tabs each count as one unit when determining whether indentation matches. Code with mixed tabs and spaces within different lines of the same comment will not be grouped.