В чем преимущество использования @discussion в комментариях?

Question

Я вижу @discussion в некоторых примерах кодов. Мой вопрос: в чем преимущество использования этого ключевого слова?

Я предполагаю, что это создаст лучшую документацию. Я попытался выполнить поиск в Google и Stackru, но вместо того, чтобы использовать это ключевое слово, я получил много примеров кода. Благодарю.

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

Answer 1

@discussion тег, используемый в Apple HeaderDoc

Эта страница содержит следующее описание:

Блок текста, который подробно описывает функцию, класс, заголовок или тип данных. Это может содержать несколько абзацев. @discussion может быть опущен, как описано выше.

@discussion должен присутствовать, если у вас есть имя из нескольких слов для типа данных, функции, класса или заголовка.

Блок @discussion заканчивается только тогда, когда начинается другой блок, такой как тег @param.

По сути, это описание с немного вводящим в заблуждение названием тега.