小编典典

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

all

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

支持哪些命令,哪些不支持?
它们的任何用法与 doxygen 不同吗?


阅读 88

收藏
2022-07-12

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

在哪里查看文档:

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

在此处输入图像描述

这将显示简短的文本(没有格式);如果不存在简短文本,它将显示所有文本的串联,直到第一个@block;如果不存在(例如,您以@return
开头),那么它将连接所有删除所有@commands 的文本。

2. Option-单击标识符名称:

在此处输入图像描述

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

(见第一个屏幕截图。)

4. 在多氧

由于 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 那样使用它们。您可以在
AVCaptureOutput.h 等文件中查看 Apple 的使用示例。

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

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

充其量,关键字会在描述字段中产生一个新行(例如@discussion)。在最坏的情况下,关键字和它后面的任何文本都不会出现在快速帮助中(例如@class)。

2022-07-12