@bug and @warning formatting engulfs subsequent paragraphs #109

Open
clozach opened this Issue May 25, 2011 · 13 comments

Comments

Projects
None yet
7 participants
@clozach

clozach commented May 25, 2011

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> {
...
@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz May 25, 2011

Owner

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

Owner

tomaz commented May 25, 2011

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

@karlwa

This comment has been minimized.

Show comment Hide comment
@karlwa

karlwa Jan 8, 2012

The most MD-like way IMO would be to close it with another @warning.

karlwa commented Jan 8, 2012

The most MD-like way IMO would be to close it with another @warning.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Jan 12, 2012

Owner

That's how it works now.

Owner

tomaz commented Jan 12, 2012

That's how it works now.

@smono

This comment has been minimized.

Show comment Hide comment
@smono

smono Apr 21, 2012

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.

smono commented Apr 21, 2012

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.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Apr 21, 2012

Owner

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.

Owner

tomaz commented Apr 21, 2012

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.

@jeffla

This comment has been minimized.

Show comment Hide comment
@jeffla

jeffla Sep 27, 2013

Adding another @discussion for the second line (desired to be outside the @warning block) worked for me.

jeffla commented Sep 27, 2013

Adding another @discussion for the second line (desired to be outside the @warning block) worked for me.

This comment has been minimized.

Show comment Hide comment
@ghost

ghost Oct 9, 2013

What should be done when wanting to include @warning's inside a -template document (included with --include)?

ghost commented Oct 9, 2013

What should be done when wanting to include @warning's inside a -template document (included with --include)?

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Oct 9, 2013

Owner

It should just work (I think :), the same way as in code comments.

Owner

tomaz commented Oct 9, 2013

It should just work (I think :), the same way as in code comments.

This comment has been minimized.

Show comment Hide comment
@ghost

ghost Oct 9, 2013

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.

ghost commented Oct 9, 2013

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.

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Oct 9, 2013

Owner

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.

Owner

tomaz commented Oct 9, 2013

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.

@Obbut

This comment has been minimized.

Show comment Hide comment
@Obbut

Obbut Jan 21, 2014

@christopherlord
I'm getting around this issue this way in readme.markdown:

@warning Insert warning text here

@discussion Continue here

Obbut commented Jan 21, 2014

@christopherlord
I'm getting around this issue this way in readme.markdown:

@warning Insert warning text here

@discussion Continue here
@NSProgrammer

This comment has been minimized.

Show comment Hide comment
@NSProgrammer

NSProgrammer Aug 28, 2014

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

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

@tomaz

This comment has been minimized.

Show comment Hide comment
@tomaz

tomaz Aug 29, 2014

Owner

This is definitely not a feature :)

Owner

tomaz commented Aug 29, 2014

This is definitely not a feature :)

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