objective-cdocumentationcommentsheaderdoc

What's the benefit of using @discussion in comments?

I'm seeing @discussion in some sample codes. My question is, what's the benefit of using this keyword?

I suppose it will generate better documentation. I tried to search on Google and Stackoverflow, but got a lot of code samples instead of how to use this keyword. Thanks.

// Example
/*!
    @method     blabla method name
    @discussion blabla discuss here
    @param      blabla describe the parameters
    @result     blabla results
 */
Solution

  • @discussion is a tag used in Apple's HeaderDoc.

    This page includes the following description:

    A block of text that describes a function, class, header, or data type in detail. This may contain multiple paragraphs. @discussion may be omitted, as described above.

    @discussion must be present if you have a multiword name for a data type, function, class, or header.

    An @discussion block ends only when another block begins, such as an @param tag.

    So it's essentially a description with a slightly misleading tag name.