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

Question

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

objective-cdocumentationcommentsdoxygenxcode5

196

Xcode 5的一个新功能是使用特殊注释语法来记录您自己的代码。格式类似于doxygen，但只支持那些功能的子集。

支持哪些命令，哪些不支持？
它们的用法是否与doxygen有所不同？

- Senseful

4个回答

16

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
    */

- Senseful

9

Senseful:

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

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

我在.h文件和.m文件中得到了不同的结果。当文档注释在头文件中时，我无法获得换行符。

- weezma2004

5

大多数格式在Swift 2.0中已更改（截至Xcode7 ß3，也适用于ß4）。

取而代之的是- parameter thing: description of thing，而不是Swift 1.2中的:param: thing description of thing。

大部分关键字现在已被替换为- [keyword]: [description]，而不是:[keyword]: [description]。目前不能使用的关键字包括abstract、discussion、brief、pre、post、sa、see、availability、class、deprecated、method、property、protocol、related、ref。

- mittens

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Senseful · Accepted Answer

这里是截至Xcode 5.0.2我所发现的所有选项示例： enter image description here

这段代码生成了上述内容：

/** 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 and \b都是相同的含义.)
这些命令通常出现在它们所描述的项之前。（例如：如果要记录一个属性，则注释必须出现在@property文本之前。）它们也可以在同一行上后置，使用 /*!<, /**<, //!<, ///<等标识。
您可以向类、函数、属性和变量中添加文档。
所有这些命令都会以深绿色文本显示，表示它们是有效命令，但@returns除外。
在最新更改的文档显示之前，您可能需要构建项目（或重新启动Xcode）。

查看文档的位置：

1.在代码补全期间，您将看到简短的文本：

enter image description here

这将显示简短的文本（没有格式）；如果不存在简短的文本，则将显示所有文本连接成第一个@block；如果不存在（例如：以@return开头），则将所有文本连接起来剥离所有@命令。

2. 选项-单击标识符名称：

enter image description here

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

（请参见第一个屏幕截图。）

4. 在Doxygen中

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

其他说明

有关Doxygen及如何记录Objective-C代码的一般介绍，请参阅此页面。

支持一些命令的描述：

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

以下不起作用：

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

以下不受支持（它们甚至不会以深绿色出现）：

\cite
\docbookonly
\enddocbookonly
\endinternal
\endrtfonly
\endsecreflist
\idlexcept
\mscfile
\refitem
\relatedalso
\rtfonly
\secreflist
\short
\snippet
\tableofcontents
\vhdlflow
\~
\"
.
::
\|

Apple保留关键字：

Apple使用了一些看似保留的关键字，这些关键字只适用于他们的文档。虽然它们以深绿色出现，但看起来我们不能像Apple那样使用它们。您可以在诸如AVCaptureOutput.h之类的文件中看到Apple的用法。

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

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

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