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

ABC_0的_之一是能够使用特殊的注释语法来记录您自己的代码。该格式类似于doxygen，但似乎仅支持那些特征的子集。

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

39410 次浏览
小开
最佳答案

下面是我在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 */，或者以///或//!作为前缀。
  • 这些命令使用@（标题文档样式）或\（多氧样式）前缀。（即，@b和\b都执行相同的操作。）
  • 这些命令通常出现在它们所描述的项目之前。（即，如果您尝试记录属性，则注释必须位于@property文本之前。）它们可以位于同一行的后面，/*!<，/**<，//!<，///<。
  • 您可以将文档添加到类、函数、属性和变量。
  • 所有这些命令都以深绿色文本显示，表示它们是有效命令，但@returns除外。
  • 在文档的最新更改出现之前，您可能需要构建项目（或重新启动Xcode）。

查看文档的位置：

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

enter image description here

这将显示简短的文本（没有格式）。如果不存在简短文本，它将显示直到第一个@块的所有文本的连接。如果不存在（例如，您以@return开头），则它将包含所有文本，并删除所有@命令。

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

enter image description here

在快速帮助检查器面板中

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

4.在Doxygen中

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

其他注意事项

有关doxygen的一般介绍以及如何记录Objective-C代码，这一页似乎是一个不错的资源。

一些受支持命令的说明：

  • @brief：将在描述字段的开头插入文本，并且是在代码完成过程中显示的唯一文本。

以下情况不起作用：

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

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

  • \引用
  • \DocBookOnly
  • \EndDocBookOnly
  • \结束内部
  • \endrtfonly
  • \endseCrefList
  • \idlexcept
  • \MSC文件
  • \refitem
  • \也相关
  • \rtfonly
  • \SecrelList
  • \短
  • \片段
  • \目录
  • \vhdlflow
  • \~
  • \"
  • .
  • ::
  • \|

Apple保留关键字：

苹果使用的似乎是只在其文档中起作用的保留关键字。虽然它们以深绿色出现，但看起来我们不能像苹果那样使用它们。您可以在avcaptureoutput.H等文件中看到Apple的用法示例。

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

  • @Abstract，@Availability，@Class，@Discussion，@Deprecated，@Method，@Property，@Protocol，@Related，@Ref.

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

小开

有意义的：

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

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

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

小开

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

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

而不是:param: thing description of thing （如在Swift 1.2中）

现在- parameter thing: description of thing

关键字的:[keyword]: [description]7已替换为- [keyword]: [description]，而不是:[keyword]: [description]。目前，不起作用的关键字列表包括：abstract、discussion、brief、pre、post、sa、see、availability、:[keyword]: [description]0、:[keyword]: [description]1、:[keyword]: [description]2、:[keyword]: [description]3、:[keyword]: [description]4、:[keyword]: [description]5、:[keyword]: [description]6。


提交答案