Headerdoc support #95

Closed
macmade opened this Issue Apr 14, 2011 · 1 comment

Comments

Projects
None yet
2 participants

macmade commented Apr 14, 2011

It would be great to also have support for Apple's headerdoc comments.

IMHO, they are much more designed for C and Objective-C than JavaDoc style comments.

For a quick implementation, the main difference is the starting tag, which is /*! instead of /**, and the @result tag instead of @return one.

The full header doc specification is available from Apple:
http://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html

Thanks a lot for your software by the way : )

Owner

tomaz commented Apr 15, 2011

Some of the differences should be very simple to add (like those you've mentioned), some would probably require more work and some aren't even needed in appledoc (@abstract, @discussion etc. - although these could easily be ignored to get nicer output).

I've tried headerdoc among other similar tools, before decided to roll out my own, but found it a bit too restrictive: it required using @Class and @method for example - this is all stuff that should be extracted from the surrounding context. On of the my greatest focus when designed appledoc 2 was to keep source code comments as simple as possible, so Markdown seemed like a perfect candidate.

tomaz was assigned Apr 29, 2011

tomaz closed this in 05b2e46 May 11, 2011

@tomaz tomaz added a commit that referenced this issue Dec 24, 2011

@tomaz tomaz 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 :)
2e063c0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment