Support all ObjC documentation commands

[jessesquires]

In testing the ObjC docs parsing (#367), I found that @discussion is not parsed.

However, @note does work, so this probably isn't high priority to fix.

I'm assuming this is because Swift supports - note:, but not - discussion:.

Screenshot of @discussion:

You can see @note working in this case in the final docs here.

[jpsim]

How would you expect @discussion to work? Same as @note? e.g. sidebar with DISCUSSION as mini-title?

Do you know if there's an exhaustive resource listing all the ObjC doc commands like Erica Sadun's reference for Swift?

[jpsim]

This is the best reference I could find: http://stackoverflow.com/a/19169271/373262

I've updated this issue title to reflect adding support for all these commands.

[jessesquires]

How would you expect @discussion to work? Same as @note?

:+1: I think so.

After some more thought, I'm not completely convinced this is worth it. To me, note and discussion are basically synonyms. Maybe we should just document the accepted keywords? On the other hand, using @discussion is probably somewhat common.

Do you know if there's an exhaustive resource listing all the ObjC doc commands?

Also not sure how useful/valuable some of these other keywords are, or how frequently people would use them? Most valuable are probably @pre, @post, and @invariant. The others.... meh. :unamused:

[jpsim]

I think we should just support them all, unless you can think of valid reasons not to. It's pretty straightforward to do.

[nlutsenko]

The most impactful one would be actually @deprecated, which might involve slightly more css work, since the default style is to cross out the declaration as well.

[shpakovski]

I'm trying to build documentation for an Objective-C project, but multiline @code-@endcode blocks are ignored by Jazzy.

Do you know any alternative supported by Xcode? It looks like Apple IDE does not recognize in.hand.m` files.

P. S. I also tried @verbatim-@endverbatim, \code-\endcode, and \verbatim-\endverbatim. No success.

UPD: I found 2 possible solutions and committed them into Jazzy and SourceKitten. Although I know they are lame 😊 So please consider to fix this stuff in a proper way. Thanks in advance!

[JanC]

Hi, I'm also looking for a way to include code snippets in the documentation. As mentioned the @code and @endcode do not work. When I use the markdown

``` ... ```

the generated jazzy html formats correctly the code but not Xcode when I option click on a method.

[istx25]

Any progress on this? I see @shpakovski's commits but not sure if they resolved this or were merged in. Would love an update. :)

[jpsim]

No, I think @shpakovski's commits were contained to that fork.

[melbic]

I'm stuck with the @code problem as well. @shpakovski could you please create a pull request to merge your fix into jazzy?

[shpakovski]

@melbic I don’t think those fixes are good for production, so they are not worth PR. Sorry for the slow reply!