【问题标题】：What are the new documentation commands available in Xcode 5? [closed]Xcode 5 中提供了哪些新的文档命令？ [关闭]
【发布时间】：2013-10-10 16:42:45
【问题描述】：

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

支持哪些命令，哪些不支持？
它们的用法与 doxygen 有什么不同吗？

【问题讨论】：

标签： objective-c documentation comments doxygen xcode5

【解决方案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 开头），那么它将连接所有删除所有 @commands 的文本。

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

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

（见第一张截图。）

4。在 Doxygen 中

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

其他说明

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

部分支持的命令说明：

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

以下不起作用：

\n: 不生成换行符。创建换行符的一种方法是确保该行上没有任何内容。一个空格字符都没有！
\example

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

\引用
\docbookonly
\enddocbookonly
\endinternal
\endrtfonly
\endsecreflist
\idlexcept
\mscfile
\refinem
\也相关
\rtfonly
\secreflist
\短
\sn-p
\目录
\vhdlflow
\~
\"
.
::
\|

苹果保留关键字：

Apple 使用的似乎是保留关键字，仅在其文档中有效。尽管它们以深绿色显示，但看起来我们不能像 Apple 那样使用它们。您可以在 AVCaptureOutput.h 等文件中查看 Apple 的使用示例。

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

@abstract、@availibility、@class、@discussion、@deprecated、@method、@property、@protocol、@related、@ref。

在最好的情况下，关键字会在描述字段中产生一个新行（例如@discussion）。在最坏的情况下，关键字及其后面的任何文本都不会出现在快速帮助中（例如@class）。

【讨论】：

感谢您的描述。希望 Apple 将其复制到 Xcode 手册中；)
使用 @ 符号代替 \ 也可以。
+1 很棒的收藏！如何在快速帮助中添加指向其他班级快速帮助的链接？
您也可以使用@c在打字机文本中显示下一个单词，如Returns an @c NSString or @c nil.。
您是否找到一种方法让 URL 出现在 Option-click 弹出窗口中？例如，如果您按住 Option 键单击 -[CADisplayLink addToRunLoop:forMode:]，则说明包含指向其他类的命名链接（但我认为面向 Web 的 URL 也很有用）。

【解决方案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
    */

【讨论】：

【解决方案3】：

有道理：

您可能需要在文档的最新更改出现之前构建您的项目。

有时这对我来说还不够。关闭 Xcode 并打开项目备份通常可以解决这些情况。

我在 .h 文件和 .m 文件中也得到了不同的结果。当文档 cmets 在头文件中时，我无法获取新行。

【讨论】：

【解决方案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、@9876543333@、@987654 @、method、property、protocol、related、ref。

【讨论】：