Getting reference error from appledoc when embedding code in comments - objective-c

Question

I have some code comments like this:
/**
How to use this method.
#discussion To use it, do something like the following
id hook = [[STDeallocHook alloc] initWithBlock:^{
// Do something when 'hook' is dealloced
}];
*/
So the code example is indented with 4 spaces. When I compile the docset with appledoc, it compiles correctly and shows the code as code in the API reference I generate. However back in XCode (Where I have appledoc creating warnings for issues in the doco) I get the warning:
Invalid [[STDeallocHook alloc] reference found hear STDeallocHook.h#16, unknown object: [STDeallocHook !
I think what's happening is that appledoc is looking for markdown links inside the code block.
How can I stop this warning from appearing?

Answer 1

I've been unable to stop it as well. It looks like it's been a known bug since 2011, but it's still broken.
Interestingly enough, I don't get it for everything. In a large code example, I'll only get a few of them... still haven't figured out how it determines to cause me grief or not...
Workarounds
This works around the warning, and looks fine in the generated documentation, but looks like crap in plain text: substitute the leading [ with the HTML escape code [
Future Fix
Supposedly, the mythical version 3 has addressed it, but I can't find any mention of an ETA for it. There is a "3.0exp1" branch from March 2012, and a "3.0dev" branch from October 2014.
If you have both the time and inclination, maybe you can see how it was fixed and patch it yourself (though the codebase has apparently changed a ton since then).
My Attempt
I felt unsatisfied with that answer, so, I went back and looked at the source code. First time in that code. It's not exactly easy to navigate... and none of the classes are documented, which I find quite strange, especially for a documentation tool.
Anyway, I think I know why I only get the warning sometimes. The parser treats all underscores as formatting markers. Thus, if it finds two of them in the same "block" of text, it splits them up. Since the code I tested on had category documentation, only the last one encountered in each "block" caused a warning... because all the others were treated as italics... and then ignored.
Also, it seems that I may be able to coerce it into skipping source-code blocks if they are marked as either...
#code
[self wjh_doSomething];
#endcode
or
```
[self wjh_doSomething];
```
or
~~~
[self wjh_doSomething];
~~~
The first is common in documentation blocks, the latter two in markdown.
It's a hack, but it seems to work. I sent a PR, which can be found here. Who knows if it will get accepted, but feel free to try it out yourself if you are so inclined.
I think I'll at least use it locally, as it cleans up a ton of warnings for me... and I may just go try to regenerate all my documented stuff to boot.
Edit
Well, I guess I should have gone and looked at the open PRs first. There seems to be a PR already sitting there that deals with the same issue, that has been there since May. It would have saved me time... but it was a little fun experimenting with it a bit ;-)
You may want to use that one... it seems to be simpler. Simpler is better, but I have not used that one and I'm not sure it completely ignores the blocks, but he seems to have quieted the warnings with his patch.
That one does not support #code/#endcode, which I'm glad to have.