3

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
 */
Matthew Strawbridge
  • 19,940
  • 10
  • 72
  • 93
lichen19853
  • 1,410
  • 2
  • 14
  • 21
  • Can you give an example, or add some better tags so the context is clear? – SimonMayer Feb 06 '12 at 19:36
  • Yes sure, edited the original post. – lichen19853 Feb 06 '12 at 23:03
  • 2
    what language is it? I'm not aware of any special significance in the languages I'm familiar with, but if you tag this question with the appropriate language, someone else may be able to answer. – SimonMayer Feb 06 '12 at 23:22
  • Did some research, thanks guys. It's supported by multiple languages. Since it's developed by Apple, it's very popular with Obj-C; but it's also compatible with C++ and other languages. – lichen19853 Feb 10 '12 at 07:49

1 Answers1

3

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

Matthew Strawbridge
  • 19,940
  • 10
  • 72
  • 93