Xcode 5中提供了哪些新的文档命令？ [英] What are the new documentation commands available in Xcode 5?

问题描述

看起来是一个很好的资源。

一些支持的命令的说明：

• @brief ：将在说明字段的开头插入文本，

以下内容不起作用：

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


• \example

以下是不支持的（它们甚至不会以深绿色显示）：

• \cite


• \docbookonly


• \enddocbookonly


• \endinternal


• \endrtfonly


• \endsecreflist


• \idlexcept


• \mscfile


• \refitem


• \relatedalso


• \rtfonly


• \secreflist


• \short


• \snippet


• \tableofcontents


• \vhdlflow


• \〜


• \


• / li>
  
• ::


• \ |

$ b 保留的关键字：

苹果使用看起来像保留的关键字，只在他们的文档中工作，虽然它们显示为深绿色，看起来像我们不能使用它们作为苹果。您可以在文件中查看Apple的使用示例，如AVCaptureOutput.h。

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

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

最多时，关键字将在描述字段中引入一个新行（例如@discussion）。在最坏的情况下，关键字和其后的任何文字将不会出现在快速帮助中（例如@class）。

One of Xcode 5's new features is 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.

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

解决方案

Here is an example of all the options I have found as of 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 @ (headerdoc style) or the \ (doxygen style) prefix. (I.e. @b and \b both 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 @property text.) 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.

Where to see the documentation:

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

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.

2. Option-clicking an identifier name:

3. In the Quick Help Inspector panel

(See first screenshot.)

4. In Doxygen

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

Other Notes

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

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.

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

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
• \~
• \"
• .
• ::
• \|

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.

Here is a list of some of those keywords:

• @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).

这篇关于Xcode 5中提供了哪些新的文档命令？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！