给你的Objective-C代码加文档注释

By http://blog.csdn.net/situee

Xcode 5 开始就支持显示代码的文档注释

除了传统的HeaderDoc标记，HeaderDoc 8还支持JavaDoc标记。并且支持很多语言，如AppleScript, Bourne Shell, Java, Javascript, Perl, Python, Ruby, etc.

In addition to traditional HeaderDoc markup, HeaderDoc 8 supports JavaDoc markup. HeaderDoc 8 supports a wide range of languages

HeaderDoc 支持一些常用的JavaDoc和Doxygen的相似的tags

例如 @since (@availability), @details (@discussion), and @description (@discussion)

"HeaderDoc supports some common JavaDoc and Doxygen synonyms for other tags:  @since (@availability), @details (@discussion), and @description (@discussion) "

VVDocumenter-Xcode Xcode插件，可自动生成注释块

下载运行后会自动安装到Xcode，重启Xcode之后就可以用了。
输入 /// 就会自动生成注释块。

我们常用到的标签，基本上javadoc和doxygen的都支持和兼容。

@breif, @description, @param, @return, @author, @date, @version, @see, @code @endcode

By http://blog.csdn.net/situee

Reference

Apple HeaderDoc User Guide
https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html

更多Doxygen标签见
http://www.stack.nl/~dimitri/doxygen/manual/commands.html

Using Doxygen to Create Xcode Documentation Sets
https://developer.apple.com/legacy/library/featuredarticles/DoxygenXcode/_index.html

Documenting in Xcode with HeaderDoc Tutorial
http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial

以下是来自stackoverflow的总结:

http://stackoverflow.com/a/19169271/111277

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 textwhile (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 \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 @property text.) They can come afterwards, on the same line, with /*!<, /**<, or //!<.
• 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).