tomaz
@bug and @warning formatting engulfs subsequent paragraphs
The code below results in a blue warning block that encapsulates both commented lines. If I change @warning to @bug, the block turns yellow, but still encompasses both lines, rather than just the first one.
/**
@warning Testing. Inside warning paragraph.
This should fall outside warning style.
*/
@interface MyAppDelegate : NSObject <UIApplicationDelegate> {
...
This is actually appledoc feature: this way you can have multiple paragraphs inside a box, which is what Apple does sometimes. My usage is to put @warning or @bug at the end of the description, just above method directives (@param, @return etc.). But if you want to have box in between description paragraphs, then some end-of-block marker should be added. As non obtrusive and Markdown-like as possible... I'll leave this issue opened for suggestions for a while to gather different ideas...
I tried to use the warning inside a -template document included with --include, and got the same behaviour as reported here.
The problem is, in a code comment it makes sense to place the @warning last, but not necessarily in a code companion document. In that case, it might even make more sense to place the warning at the top - right after the page title, for instance.
I have tried to close it with another @warning, but it does not get recognized.
I agree it's not ideal, although didn't find good solution to have it work both ways and decide on case by case. This would require some syntax outside Markdown default. I'm currently focusing on updating the code to make it more maintainable. Perhaps an idea will pop in between. I'm also open for any suggestions.
Adding another @discussion for the second line (desired to be outside the @warning block) worked for me.
What should be done when wanting to include @warning's inside a -template document (included with --include)?
Using @bug or @warning consumes the rest of the document, I can't figure out how to end it? I've tried doing:
@warning test
@warning
And that doesn't appear to work either.
That's correct - it's so that you can include multiple paragraphs, lists etc. You can only end it with another @bug or @warning. So for the moment being use them at the bottom of the document.
@ChristopherLord I'm getting around this issue this way in readme.markdown:
@warning Insert warning text here
@discussion Continue here
This also has the annoying side effect that if you @warning in the comment of a class declaration and have additional comments on a category for that same class, when the category comments are pulled into the documentation for the class they will be placed in the @warning section. I don't believe that can be argued as a feature.
/**
@warning Some warning
*/
@interface Foo
@end
/**
Some plain comments
*/
@interface Foo (SomeCategory)
@end
Some plain comments will be under the @warning in the output documentation
