What are the new documentation commands available in Xcode 5?
Solution 1
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).
Solution 2
Swift 2.0 uses the following syntax:
/**
Squares a number.
- parameter parameterName: number The number to square.
- returns: The number squared.
*/
Notice how @param
is now - parameter
.
You can also now include bullets in your documentation:
/**
- square(5) = 25
- square(10) = 100
*/
Solution 3
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.
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.
Solution 4
Most of the formatting has changed for Swift 2.0 (as of Xcode7 ß3, also true in ß4)
instead of :param: thing description of thing
(as it was in Swift 1.2)
it is now - parameter thing: description of thing
Most of 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
.
Senseful
Updated on July 16, 2022Comments
-
Senseful almost 2 years
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? -
Quxflux over 10 yearsThanks for the description. Hopefully Apple will copy it into the Xcode manual ;)
-
Dafydd Williams over 10 yearsThese commands will also work in a
/** block */
, too. -
Drewsmits over 10 yearsUsing the @ symbol instead of \ works as well.
-
Selvin over 10 years+1 Great collection! How to add a link to another Class's quick help in the quick help?
-
MLQ over 10 yearsYou can also use
@c
to display the next word in typewriter text, as inReturns an @c NSString or @c nil.
. -
David H over 10 yearsI wrote a long header, it wouldn't show, and I tried changing text over and over. Finally I deleted the Derived Folder (in Organizer) and bam, I got the comment. YMMV
-
David H over 10 yearsNote that right now as of Xcode 5.1, class methods don't work.
-
LightningStryk about 10 yearsHow did you get your custom doc comments to show up in the search apple documentation viewer?
-
Zev Eisenberg about 10 yearsHave you found a way to get a URL to appear in the Option-click popup? For example, if you Option-click on
-[CADisplayLink addToRunLoop:forMode:]
, the description includes named links to other classes (but I suppose Web-facing URLs would be useful too). -
poetmountain about 10 yearsGreat list. It seems strange that Apple provides no @default option to denote default values for properties. This is a sore point in Apple's own docs, as default values are haphazardly documented.
-
theory about 10 yearsSuper helpful. But man, inline tags like
@b
affect only a single word! Radar or GTFO! -
Gerald Eersteling almost 10 yearsIs there a way for the tags to affect multiple words? An example:
Hi I am a @b snippet @b of @b documentation!
gives an output of: "Hi I am a snippetofdocumentation !". It does what one would expect, but also deletes spaces :| Anyone found a solution? -
Zev Eisenberg over 9 years@Gee.E have you tried multiple spaces? Not sure if it works, but worth a shot. Also worth filing a radar :\
-
Gerald Eersteling over 9 years@ZevEisenberg Yes, tried that as well. Before asking I tried several things such as multiple spaces. Anyway, I'm going to post this as a question. Would probably be better to discuss it separately.
-
Quxflux over 9 yearsDoes anyone have an idea how to include local images? Remotely hosted images can be embedded using <img src="test.png">. This does however not work for local files using file://.
-
Iulian Onofrei over 9 yearsWhat is the difference between
result
,return
andreturns
? -
Ky - over 9 yearsCould you also supply explanation for what is expected here? For instance, what does
@invariant
specify? -
ravron over 8 yearsIf you use doxygen commands, you can do multi-word formatting. E.g.
I want <tt>this part</tt> to be bold
yields "I want this part to be bold". Xcode 7.1.