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

Question

Xcode 5's new features之一是能够使用特殊注释语法记录您自己的代码。格式类似于doxygen，但似乎只支持those features的子集。

支持哪些命令，哪些命令不支持？
他们的任何用法都不同于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文本之前。）他们可以在/*!<，/**<，{{ 1}}，//!<。
• 您可以向类，函数，属性和变量添加文档。
• 除///<外，所有这些命令均以深绿色文字显示，表示它们是有效命令。
• 您可能需要在文档的最新更改出现之前构建项目（或重新启动Xcode）。

在何处查看文档：

1。在代码完成期间，您将看到简短的文本：

这将显示简短的文字（没有格式化）;如果不存在简短文本，它将显示直到第一个@block的所有文本的串联;如果不存在（例如，以@return开头），那么它将连接所有@jmands的文本。

2。按住Option键并单击标识符名称：

3。在“快速帮助”检查器面板中

（见第一张截图。）

4。在Doxygen

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

其他注释

有关Doxygen的一般介绍以及如何记录Objective-C代码，this page似乎是一个很好的资源。

一些支持的命令的描述：

• @brief：将在说明字段的开头插入文字，并且是代码完成期间唯一会显示的文字。

以下不起作用：

• @returns：不生成换行符。创建换行符的一种方法是确保该行没有任何内容。甚至不是一个空格角色！
• \n

不支持以下内容（它们甚至不显示为深绿色）：

• \引用
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \短
• \段
• \ tableofcontents
• \ 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，{{ 1}}，see，availability，class，deprecated，method，property，protocol，{{1} }。