在评论中使用@discussion有什么好处？

Question

我在一些示例代码中看到了@discussion。我的问题是，使用这个关键字有什么好处？

我认为它会生成更好的文档。我试图在Google和Stackoverflow上搜索，但得到了很多代码示例，而不是如何使用这个关键字。谢谢。

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

- lichen19853

---

你能举个例子或添加一些更好的标签以便上下文更清晰吗？ - SimonMayer

是的，当然，已编辑原帖。 - lichen19853

这是什么编程语言？在我熟悉的语言中，我不知道有任何特殊意义，但如果您使用适当的语言标签标记此问题，其他人可能会回答。 - SimonMayer

做了一些研究，谢谢大家。它支持多种语言。由于它是由苹果开发的，因此在 Obj-C 中非常受欢迎；但它也与 C++ 和其他语言兼容。 - lichen19853

Answer 1

@discussion 是苹果公司的 HeaderDoc 中使用的标签。

这个页面 包含了以下描述：

一个详细描述函数、类、头文件或数据类型的文本块。可以包含多个段落。如上所述，@discussion 可以省略。

如果对于数据类型、函数、类或头文件使用了多个单词来命名，则必须使用 @discussion 标签。

只有当另一个块开始时（例如 @param 标签）才会结束 @discussion 块。

因此，它本质上是带有略微误导性标签名称的 描述。

- Matthew Strawbridge