Considering this example (provided by "PrimaryFeather", appledoc would fail assigning the comment to the class:
/** Class description */
@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
@interface SPBitmapFont : NSObject
With this update, parses is able to attach the comment although with a twist by always assuming the first declaration as the valid one and ignoring all others. In other words: when using such solutions, make sure the first @interface (or @protocol) is the one you'd like to see in the generated documentation. For above example this means that documented class will list NSXMLParserDelegate as adopted protocol.
Note that to properly handle this the solution was to persist any encountered comments during parsing and only update them when new comments are detected. However this lead to situations that any found comment would be used for all subsequent objects in the same file. Therefore I had to add manual resetting of comments after assigning them to an object.
*Important:* Although all unit tests pass and generated documentation looks ok, this might require additional tweaking. Let's see if some more bug reports come...
The problem was in cases like this:
/** comment */
@property (attributes) id commentedProperty;
After working on workaround for #43 (commit 4262bb8) forgot to reset comments when parsing methods and properties. Although above case worked properly in case of two methods (in fact there was a unit test specific for that situation and it passed), it didn't work if uncommented method (or property) followed commented property. This is correctly handled now, so it should work for both cases (added another unit test to cover above situation).
Thanks to "BloodDragon" for pointing this one out.