Merge pull request #145 from groue/master

Follow up to tomaz/appledoc#144
Model: add support for protocols in properties.

This fixes issue 148 at https://github.com/tomaz/appledoc/issues/148
Merge pull request #149 from lcpromptu/master

Fixes protocols support in properties. Closes #148.

Thanks to [lcpromptu](https://github.com/lcpromptu)!
Fixed DocSet generation when using companion guides. Closes #155.

When using `@see` to link in companion guides inside a class/category/protocol comment, appledoc tried to create related object description inside the token xml file. But the code that was creating token only handled classes, categories, protocols and their members; when other type of object was encountered (i.e. static document/companion guide), the method token generation was assumed which failed due to missing data.

Anyway, the fix introduced here first checks all (currently) supported object types and returns `nil` for unsupported types, then the code that prepares data for template renderer checks for `nil` and only adds related object if there is some.
Fixed property name detection. Closes #153.

The problem was with recent support for termination macros: originally appledoc always took the last component for property name, but that's obviously not working for termination macros. So the new code took the second component which broke cases like `IBOutlet UIView *name`. To compensate, the code now tries to handle the stuff more intelligently.

**Note:** Just a side note: recent pull requests broke several unit tests, including method/property handling ones, so there might be additional incompatibilities! Will need to check those too!
Fixed remaining unit tests, now again to 0 faults...

**Note:** Should convert to sen test as it's supported natively by Xcode 4 and provides much better IDE integration...
Changed how single/multi line comments are parsed. Partially addresses #154.
Fixed usage of single star as bold marker (kind of). Closes #154.

The problem with star delimited unordered lists was in appledoc comment preprocessor which consumed single star and replaced them with double star markers so that text would be emitted in bold. That's actually a feature of appledoc which allows single stars be used for bold markers, but may break compatibility with Markdown as the result. As there's no reliable way of determining whether the user wants to have star delimited, I decided to go the route I had in my mind for some time now: introduce another command line switch that would prevent handling single stars. It's on/off solution, so not the best one, but everyone can choose at least... Also updated [online documentation](http://gentlebytes.com/appledoc-docs-examples-basic/index.html#compatibility) with example of using the new switch.

**Important:** As of this version on, single star handling is **off** by default! This may break backwards compatibility with some folks, but I feel it's better to keep as Markdown compatible for new people as possible...
Upgraded project to Xcode 4.2
Implemented `#pragma mark -` handling. Closes #140 and #156.

The problem was in appledoc interpreting `-` after `#pragma mark` as start of instance method definiton/declaration and as it failed to match open parenthesis after, it skipped the rest of unmatched symbols until next match was found. This effectively resulted in first method or property after the pragma being skipped. The fix herein should handle these situations...

**Implementation note:** Note that the code first goes on and tries to match a method (due to minus sign). Method matching code was updated so that it skips repeating minus and plus until followed by an open parenthesis. This covered methods after pragma, but property definition still remained problematic. Although method matching properly exits once it finds `@property` token, the token is consumed before giving a chance of matching a property. Hence the code had to be updated to prevent consuming. This successfully parsed the property, however property matching code reset comments. So a class level flag was introduced that is set inside method matching code and is checked before resetting comment when parsing property; if flag is set, comments are not reset, otherwise they are. Not the prettiest solution, but (seems) to work...
Fixed html literals handling with doc set. Closes #107.

Today got a feedback from Apple on my bug report:

> When constructing the Tokens.xml file, you have to remember that the file needs to be valid XML first and foremost.  You cannot have a standalone & or an unrecognized XML &entity; in an XML file.  They have to be encoded for the XML first.  For example, if you have the abstract string "This & that", you need to store it in the XML file like this:
>
>     <Abstract>This &amp; that</Abstract>
>
> When docsetutil (or any XML parser) reads the abstract string, the &amp; will get converted into a plain & character.  If you are trying to display a literal entity string, such as "This &asterisk; that", you need to still escape the ampersand character:
>
>     <Abstract>This &amp;asterisk; that</Abstract>
>
> However, if you want your entity to render as a particular character when displayed in QuickHelp, you need to mark the string as HTML:
>
>     <Abstract type="html">This &amp;asterisk; that</Abstract>
>
> The XML parser will see the abstract string as "This &asterisk; that" and will pass it on to the HTML parser, which will then render the string like "This * that".
>
> Please let us know if that information helps you resolve the issue.

Turns out the fix is to change abstract type to html and replace all occurrences of `&` with `&amp;` in token xml files, so for example `&ndash;` should become `&amp;dash;`. Tried few tests on it and works for me. The literals (i.e. `&ndash;`) are properly rendered in Xcode quick help and html. Took a while, but this solution didn't occur to me... Have a go and report back if you have any issue with this.
Updated build number to 741.
Fixed install script to better handle paths with whitespace, thanks to koyachi. Closes #159.
Increased build number to 743.
Fixed category cross references formatting. Closes #160.

The problem was in Discount parsing URL with parenthesis `[text](path/with(parenthesis).html)` as `<a href="path/with(parenthesis">text</a>.html)`. Not sure if this is Markdown rule of how paths with parenthesis are handled, but the simplest solution was to convert category paths to not use parenthesis.

**IMPORTANT:** From here on, category paths are constructed with a plus sign: `class+category`. Previously they were using format `class(category)`. Although this should be simply upgraded by running appledoc, it may break external links. Something to keep in mind...
Improved support for HeaderDocs

Added a few string manipulations that bring HeaderDoc comments closer
in line with AppleDoc:
1. Makes sure that @param and @result are at the end of a comment
before parsing.
2. Removes lines starting with @class, @method, @property, @protocol
3. Removes keywords that are not supported by AppleDoc such as
@abstract and @discussion
4. Replaces @methodgroup and @group with @name
Merge pull request #163 from felixLam/master

Improved support for HeaderDocs
Fixed unit tests for handling paths to category files. References #160.
Cleaned up HeaderDoc parsing code and made it optional. References #95 and #163.

As comment preprocessing method in `GBTokenizer` became quite large, I divided it into separate methods by taking out header doc preprocessing. Also made header doc preprocessing optional and disabled by default (except the bare minimum covered by #95). To enable it, use `--preprocess-headerdoc` command line switch. The reason for opting it out by default is amount of preprocessing that could break things for existing appledoc users. Probably just me being paranoid, but better safe than sorry :)
Improved Property Handling in DocSet
- Getter / setter methods are added to the DocSet tokens and linked to the property's documentation