Support for Apple style comments

[michaelochs]

First of all: I am looking into apple doc for a couple of days now and think it is an amazing product! I love it. However there are some thinks I am missing, like enum documentation.

In Apple's Event Kit framework (iOS) you can see fully documented header files, as Apple uses them - I don't know if this is by accident and if it will go away in the future, but it is there at the moment. There are a couple of stuff, that isn't supported with appledoc.

The things I found, that aren't documented are: @enum, @constant, @abstract, @discussion, @Property and @method. I don't know if there are other unsupported tags, I haven't tried everything by now.

You can find one example of a header here: http://developer.limneos.net/headers/4.0/EventKit.framework/Headers/EKEventStore.h

[tomaz]

Apple uses header doc with some custom postprocessing afaik. Headerdoc relies on many @ directives to describe the context to which comment belonfs (such as @method and @Property). In constrast, appledoc tries to get context information from the source code surrounding the comment: for example, if the comment is before a method, method name is automatically parsed from it etc. Therefore it doesn't require as much work (and repeating) from developer so it should be more DRY and less error prone. Additionally, it uses markdown for formatting comments, so it should result in as readable comments as possible. Hope this explains basic differences...

There is some support for headerdoc directives, but you must include it via --preprocess-headerdoc cmd line switch (requires 10.7 due to NSRegularExpression).

As for @abstract and @discussion: first paragraph of each comment is taken as abstract and the rest as discussion. There's also cmd line switch that lets you repeat abstract in discussion (although it may not work 100% in current version).

@enum, @constant - see #2; this is coming in 3.0 (currently on experimental branch).

[michaelochs]

It would still be nice to support @method and @Property as optional, for example if I want to have a setter and getter in my header but in the documentation it should be visible as a property and vice versa. Besides that, --preprocess-headerdoc results in tabs not beeing interpreted correctly! These get interpreted as sourcecode examples, in headerdoc they don't.
As of what I downloaded from github a couple of days ago: The automatic paragraph recognition isn't working! I see the hole text as abstract and as discussion when not putting @abstract and @discussion in front of it and if I do, I see the abstract and the discussion under the discussion part, no abstract at all.

[tomaz]

I think your issues come from having higher expectations of what headerdoc support means in appledoc, than it really does :)

Appledoc only implements basic recognition of some headerdoc @ directives, but other than that, it still uses Markdown for formatting. Hence tabs get interpreted as code blocks. And for paragraphs, you still need to put an empty line in between. You're probably using something like:

@abstract text
@discussion text

which is not interpreted as paragraph due to missing empty line... Probably not that difficult to fix during preprocessing phase, but I'm focusing on other areas at this point.

Originally I didn't implement any of headerdoc support; while I recognized value of it when transitioning to appledoc, it seemed like basically implementing another layer of comments parsing. In view of amount of time I can devote to appledoc, I went for quickest solution. It's not ideal, but appledoc was never meant as headerdoc parser. Much of headerdoc support was in fact contribution by appledoc users. I can imagine it covers needs of those particular users, so it would most likely include more...

Hope this explains your issues :)