Xcode中的文档注释是什么？

Question

此问题仅供参考。

在Xcode的“设置”窗口的“字体和颜色”标签中，有文档注释（和关键字）的设置？它们是什么？

Answer 1

随意加强此答案。

文档注释只是（Objective-C）注释标记为文档。除了可以在Xcode中设置其他颜色和字体外，它们的处理方式与普通注释相同。某些文档软件甚至可以使用这些注释来自动创建来自给定头文件和其他源代码的文档。

文档注释关键字是对文档注释中关键字后面的文本赋予语义含义的关键字。

您可以使用三个斜杠（而不是正常注释中的两个）创建内联文档注释，并阻止doc。评论有两颗星而不是一颗（而不是正常评论中的一颗）。例如：

// Normal inline comment
/// Documentation comment

/* Normal block
comment */
/** Documentation block
comment */

您可以通过在“at”符号后指定关键字（仅限一个字）来创建文档注释关键字。例如：

- (void)sendMessage: (id)sender;
/// @description Sends the receiver.
/// @available Version 1.0 through 2.2

Appledoc是一个工具，用于从源代码（包括文档注释和方法签名）创建文档集，并在需要时在Xcode中安装和重新加载。它是一个命令行程序，并提供了如何将其合并到Xcode构建过程中的说明。

有了文档集后，您可以通过首选项＆gt;将其添加到Xcode中。下载＆gt;文档

以@ -sign开头的特殊关键字也称为HeaderDoc标签。可以在the HeaderDoc User Guide中找到它们的列表。请注意，其中一些是Objective-C，一些是C ++。

Answer 2

对于那些没有观看最新主题演讲的人：使用Xcode 5，将内置此功能。它已在当前的开发人员预览中提供（称为快速帮助，如宣布的here）。

Answer 3

Xcode 5现在内置了对DOxygen风格注释的支持。所以，你可以这样评论你的方法：

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;

内联帮助将如下所示：

快速帮助将如下所示：

侧栏帮助将如下所示：

这是一个方便的代码段，您可以添加Xcode Code Snippet库以简化方法文档：

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

现在，你可以输入“doxy”和poof！你有你的doxygen模板。

Answer 4

有许多工具，例如Doxygen，Javadoc和其他工具，可识别“特殊”注释（称为文档注释），以自动生成代码文档。

通常，文档注释以特殊序列开头，例如/ **（而不仅仅是/ *），并包含通常具有特殊开始符号（如@）的特殊关键字。不同的注释文档生成器之间有很多相似之处，大多数文档生成器接受“@param”来记录参数，“@return”来记录返回值，“@throws”来记录异常，等等。

在Xcode的语法突出显示的上下文中，文档注释是具有Xcode碰巧识别的这些特殊启动序列之一的注释。应该注意的是，Xcode正确识别了一组特定的评论;例如，Doxygen工具也允许/ *！和//！ （带有感叹号）表示文档注释的开始，但Xcode无法识别它。