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构建过程中的说明.

获得文档集后,可以通过"首选项">"下载">"文档"将其添加到Xcode .

以@ -sign开头的特殊关键字也称为HeaderDoc标签.可以在HeaderDoc用户指南中找到它们的列表.请注意,其中一些是Objective-C,一些是C++.

Answer 2

对于那些谁没看最新的主题:在Xcode 5此功能将建成,是在目前的开发者预览版已经可以(被称为快速帮助,就像宣布这里).

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代码片段库以简化方法文档:

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

现在,你可以输入"doxy"和poof!你有你的doxygen模板.

Answer 4

有许多工具,如Doxygen,Javadoc和其他工具,可识别"特殊"注释(称为文档注释),以自动生成代码文档.

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

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