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

Question

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

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

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

Answer 1

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

This page включает в себя следующее описание:

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

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

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

Так что по существу описание с немного вводит в заблуждение название тега.