Interface definition in #ifdef: class description not recognized #43

Closed
PrimaryFeather opened this Issue Jan 5, 2011 · 4 comments

Comments

Projects
None yet
2 participants

This is a rather obscure problem - consider it low priority!

I have a class like this:

/** Class description */
#ifdef __IPHONE_4_0
@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
#else
@interface SPBitmapFont : NSObject
#endif
{
    // ...
}

// ...
@end

In that case, the class description is not recognized.

I guess something like that won't happen very often - but a change in the iOS SDK forces me to do it.

If any other user has a similar problem: you can use the following workaround:

#if 0
/** Class description */
@interface SPBitmapFont
#endif

#ifdef __IPHONE_4_0
@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
#else
// ... -> continue as before
Owner

tomaz commented Jan 5, 2011

I think this is completely valid expectation and appledoc should be able to handle it!

One simple solution would be to ignore the first @interface alltogether and only use second one (or last one if there were multiple cases with #elif). Or perhaps use the first one as it's "closer" to the comment. This would result in predictable behavior.

Will mark it as bug.

Owner

tomaz commented Jan 6, 2011

Fixed comments parsing for non-trivial sources. Closed by 4262bb8.

Considering this example (provided by "PrimaryFeather", appledoc would fail assigning the comment to the class:

/** Class description */
#ifdef __IPHONE_4_0
@interface SPBitmapFont : NSObject &lt;NSXMLParserDelegate&gt;
#else
@interface SPBitmapFont : NSObject
#endif

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...

That's sounds like a great solution, thanks!!

I will update to the latest development version and will post any problems I encounter.

No problems so far! Everything works as expected.

@tonklon tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012

@tomaz tomaz Fixed comments parsing for non-trivial sources. Closes #43.
Considering this example (provided by "PrimaryFeather", appledoc would fail assigning the comment to the class:

	/** Class description */
	#ifdef __IPHONE_4_0
	@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
	#else
	@interface SPBitmapFont : NSObject
	#endif

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...
4262bb8

@tonklon tonklon pushed a commit to tonklon/appledoc that referenced this issue Mar 8, 2012

@tomaz tomaz Fixed undocumented methods and properties parsing. Closes #57.
The problem was in cases like this:

	/** comment */
	@property (attributes) id commentedProperty;

	- (void)uncommentedMethod;

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.
1bf7946

This issue was closed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment