objective-c Xcode 5 中提供了哪些新的文档命令？

What are the new documentation commands available in Xcode 5?

提问by Senseful

One of Xcode 5's new featuresis the ability to document your own code with a special comment syntax. The format is similar to doxygen, but appears to only support a subset of those features.

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

Which commands are supported, and which ones aren't?
Do any of their usages differ from doxygen?

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

回答by Senseful

Here is an example of all the options I have found as of Xcode 5.0.2

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

That was generated with this code:

这是使用以下代码生成的：

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

Notes:

笔记：

• The commands must be in a /** block */, /*! block */, or prefixed with ///or //!.
• The commands work with the @(headerdocstyle) or the \(doxygenstyle) prefix. (I.e. @band \bboth do the same thing.)
• The commands usually come before the item they are describing. (I.e. if you are trying to document a property, the comment must come before the @propertytext.) They can come afterwards, on the same line, with /*!<, /**<, //!<, ///<.
• You can add documentation to classes, functions, properties,and variables.
• All of these commands appear in dark green text to signify that they are valid commands, except for @returns.
• You may need to build your project (or restart Xcode) before the latest changes to your documentation appear.

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

Where to see the documentation:

在哪里查看文档：

1. During code complete, you will see the brief text:

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

This will show the brief text (with no formatting); if no brief text exists, it will show a concatenation of all the text up to the first @block; if none exists (e.g. you begin with @return), then it will concat all the text striping away all @commands.

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

2. Option-clicking an identifier name:

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

3. In the Quick Help Inspector panel

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

(See first screenshot.)

（见第一个截图。）

4. In Doxygen

4. 在 Doxygen

Since the commands in Xcode 5 are compatible with Doxygen, you could download and use Doxygen to generate documentation files.

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

Other Notes

其他注意事项

For a general introduction to Doxygen and how to document Objective-C code, this pageseems like a good resource.

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

Descriptions of some of the supported commands:

一些支持的命令的说明：

• @brief: will insert text at the beginning of the description field, and is the only text that will appear during code completion.

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

The following don't work:

以下不起作用：

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

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

The following are not supported (they don't even appear in dark green):

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

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

• \引用
• \docbookonly
• \enddocbookonly
• \end内部
• \endrtfonly
• \endsecreflist
• \idlexcept
• \msc 文件
• \refitem
• \相关也
• \rtfonly
• \secreflist
• \短的
• \片段
• \目录
• \vhdlflow
• \~
• \"
• .
• ::
• \|

Apple reserved keywords:

苹果保留关键词：

Apple uses what appears to be reserved keywords that only works in their documentation. Although they appear in dark green, it looks like we cannot use them as Apple does. You can see examples of Apple's usage in files such as AVCaptureOutput.h.

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

Here is a list of some of those keywords:

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

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

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

At best, the keyword will cause a new line in the Description field (e.g. @discussion). At worst, the keyword and any text following it will not appear in the quick help (e.g. @class).

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

回答by Senseful

Swift 2.0uses the following syntax:

Swift 2.0使用以下语法：

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Notice how @paramis now - parameter.

请注意@param现在如何- parameter。

You can also now include bullets in your documentation:

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

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

回答by weezma2004

Senseful:

有意义：

You may need to build your project before the latest changes to your documentation appear.

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

Sometimes this hasn't been enough for me. Closing Xcode and opening the project back up usually remedies those cases.

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

I'm also getting different results in .h files and .m files. I can't get new lines when the documentation comments are in a header file.

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

回答by mittens

Most of the formatting has changed for Swift 2.0 (as of Xcode7 ?3, also true in ?4)

Swift 2.0 的大部分格式都发生了变化（从 Xcode7 开始，?3，在 ?4 中也是如此）

instead of :param: thing description of thing(as it was in Swift 1.2)

而不是:param: thing description of thing（就像在 Swift 1.2 中那样）

it is now - parameter thing: description of thing

就是现在 - parameter thing: description of thing

Mostof the keywords have been replaced by - [keyword]: [description]instead of :[keyword]: [description]. Currently the list of keywords that don't work includes, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.

大多数的关键词已被替换- [keyword]: [description]，而不是:[keyword]: [description]。目前，无效的关键字列表包括, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref。