Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Headerdoc support #95

Closed
macmade opened this Issue · 1 comment

2 participants

@macmade

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 : )

@tomaz
Owner

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 tomaz was assigned
@tomaz tomaz closed this issue from a commit
@tomaz Added basic support for headerdoc comments. Closes #95.
Note that this only adds support for headerdoc style comments (`/*! */`) and `@result` for return value. The tool could be further improved by ignoring unsupported headerdoc tags (like `@abstract`, `@class`, `@method` and similar), but I don't have time for that right now. Will close the issue for now as headerdoc comments can be extracted, and if there will be a lot of demand for this feature in the future, either this issue can be reopened or a new one created.

Also increased build number to 697.
05b2e46
@tomaz tomaz closed this in 05b2e46
@tomaz tomaz referenced this issue from a commit
@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
Something went wrong with that request. Please try again.