Xcode 5中有哪些新的文档命令？

Question

一个Xcode中5的新功能是一种特殊的注释语法来记录自己的代码的能力.格式类似于doxygen,但似乎只支持这些功能的子集.

支持哪些命令,哪些命令不支持？
他们的任何用法与doxygen有什么不同？

Answer 1

以下是我在Xcode 5.0.2中找到的所有选项的示例

这是用这段代码生成的:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

笔记:

• 这些命令必须在一个/** block */,/*! block */或作为前缀///或//!.
• 这些命令使用@(headerdoc样式)或\(doxygen样式)前缀.(即@b和\b都做同样的事情.)
• 命令通常出现在他们描述的项目之前.(也就是说,如果你想记录的属性,注释必须出现在之前@property的文本.)他们可以来之后,在同一行,用/*!<,/**<,//!<,///<.
• 您可以向类,函数,属性和变量添加文档.
• 所有这些命令都以深绿色文本显示,表示它们是有效的命令,除了@returns.
• 在显示文档的最新更改之前,您可能需要构建项目(或重新启动Xcode).

哪里可以看到文档:

1.在代码完成期间,您将看到简要文本:

这将显示简短的文字(没有格式化); 如果不存在简短的文本,它将显示直到第一个@block的所有文本的串联; 如果不存在(例如,你从@return开始),那么它将连接所有@jmands所有文本.

2.按住Option键单击标识符名称:

3.在"快速帮助"检查器面板中

(见第一张截图.)

4.在Doxygen中

由于Xcode 5中的命令与Doxygen兼容,因此您可以下载并使用Doxygen生成文档文件.

其他说明

有关Doxygen以及如何记录Objective-C代码的一般介绍,此页面似乎是一个很好的资源.

一些支持的命令的描述:

• @brief:将在描述字段的开头插入文本,并且是代码完成期间将出现的唯一文本.

以下不起作用:

• \n:不生成换行符.创建换行符的一种方法是确保该行没有任何内容.甚至不是一个空格角色!
• \example

不支持以下内容(它们甚至不显示为深绿色):

• \引用
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \短
• \片段
• \目录
• \ vhdlflow
• \〜
• \"
• .
• ::
• \ |

Apple保留关键字:

Apple使用似乎只在其文档中有效的保留关键字.虽然它们看起来是深绿色,但看起来我们不能像苹果那样使用它们.您可以在AVCaptureOutput.h等文件中查看Apple的用法示例.

以下是其中一些关键字的列表:

• @ abstract,@ availibility,@ class,@ discussion,@ deprecated,@ method,@ property,@ protocol,@ related,@ ref.

充其量,关键字将在"描述"字段中生成一个新行(例如@discussion).在最坏的情况下,关键字及其后面的任何文本都不会出现在快速帮助中(例如@class).

Answer 2

Swift 2.0使用以下语法:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

请注意@param现在怎么样- parameter.

您现在还可以在文档中包含项目符号:

/**
        - square(5) = 25
        - square(10) = 100
    */

Answer 3

Senseful:

在显示文档的最新更改之前,您可能需要构建项目.

有时这对我来说还不够.关闭Xcode并重新打开项目通常可以解决这些问题.

我在.h文件和.m文件中也得到了不同的结果.当文档注释位于头文件中时,我无法获得新行.

Answer 4

Swift 2.0的大多数格式都已更改(从Xcode7ß3开始,在ß4中也是如此)

而不是:param: thing description of thing (在Swift 1.2中)

就是现在 - parameter thing: description of thing

大多数关键字已被替换- [keyword]: [description]为:[keyword]: [description].目前不工作的关键字列表包括,abstract,discussion,brief,pre,post,sa,see,availability,class,deprecated,method,property,protocol,related,ref.