49

How can I force Xcode to show my own documentation for custom classes, methods, etc.? I'm used to Java and Eclipse, which shows me documentation for my classes as shown here:

Eclipse showing Javadocs documentation

How can I achieve the same in Xcode? Are there special comments that Xcode can recognize and display?

Xcode showing generic documentation for NSObject

AstroCB
  • 12,337
  • 20
  • 57
  • 73
Peter Štibraný
  • 32,463
  • 16
  • 90
  • 116
  • 3
    Great question! I don't actually know; I typically just command-click the class (or function, or variable, or...) name to jump to its definition. Not ideal, but you can jump right back to where you were with command-control-left arrow, so it's nearly as quick. – Ryan Ballantyne Aug 05 '11 at 15:11
  • @Ryan: thanks for suggestion. Not perfect, but it's reasonable alternative. – Peter Štibraný Aug 06 '11 at 11:01

5 Answers5

46

As of Xcode 5.0, Doxygen and HeaderDoc formatting for variables and methods is automatically parsed and rendered in the Quick Help popover. More information about it here, but here's some key bits:

/**
 * Add a data point to the data source.
 * (Removes the oldest data point if the data source contains kMaxDataPoints objects.)
 *
 * @param aDataPoint An instance of ABCDataPoint.
 * @return The oldest data point, if any.
 */
 - (ABCDataPoint *)addDataToDataSource:(ABCDataPoint *)aDataPoint;

renders in Xcode as:

As for properties, it's as easy as:

/// Base64-encoded data.
@property (nonatomic, strong) NSData *data;

When option-clicked, this lovely popover appears:

Community
  • 1
  • 1
cbowns
  • 6,295
  • 5
  • 47
  • 64
  • 1
    Very nice! Thanks for sharing. – Peter Štibraný Oct 08 '13 at 22:20
  • 5
    [Here is the full syntax guide.](https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html#//apple_ref/doc/uid/TP40001215-CH346-CHDJFEGF) Not all of it seems to be supported (for example, @link is broken). – Neal Ehardt Nov 12 '13 at 01:17
  • How can I specify @ in the description. If I use user@abc.com. Xcode only shows user.com. – nr5 Oct 28 '15 at 12:18
  • @Nil This works ok for me in Xcode 7.1 in Swift 2.1 code. screenshot: https://cloudup.com/cvtpstuUsUW – cbowns Oct 28 '15 at 23:11
  • 1
    @Nil otherwise, try backslash escaping the @ symbol. – cbowns Oct 28 '15 at 23:11
12

Well, it seems that for the classes the question hasn't still been answered, so I'll post my suggestions.

Just before the @interface MyClass : NSObject line in the MyClass.h file you use the comment like you did in your example, but adding some tags to display the text. For example the code below:

/**
 * @class GenericCell
 * @author Average Joe
 * @date 25/11/13
 *
 * @version 1.0
 *
 * @discussion This class is used for the generic lists
 */

will produce the following output: the output of the code above http://imageshack.com/a/img18/2194/kdi0.png

Community
  • 1
  • 1
Deboroh88
  • 391
  • 1
  • 6
  • 20
11

Appledoc is the best option for generating xcode documentation at the moment. Doxygen is great, but it does not generate docsets that work very well for the popups you're talking about. Appledoc isn't perfect, but we moved over to it and have been really happy with the results.

enter image description here

DougW
  • 28,776
  • 18
  • 79
  • 107
  • I tried with the sample project that appledoc provides. I ws able to add the documentation, but it doesn't show the parameters or return value descriptions as shown in your example. Can you tell me where I could be going wrong? – neeraj Aug 27 '13 at 12:16
6

It is also possible to add some code snippet in documentation like the following

Code snippet in Function Documentation in Xcode

by adding the following code 

 *  @code
 *  - (UIButton*) createButtonWithRect:(CGRect)rect
     {
        // Write your code here
     }
 * @endcode

For more details of documenting methods of a custom class you can have a look on my blog Function Documentation in Xcode.

Sauvik Dolui
  • 5,520
  • 3
  • 34
  • 44
5

To get Xcode to show documentation for your classes, you must create a documentation set for your classes using a tool like Doxygen or HeaderDoc. After creating the documentation set, you must install it using Xcode's documentation preferences. Apple has an article on using Doxygen, but it covers Xcode 3, not 4.

Using Doxygen to Create Xcode Documentation Sets

Community
  • 1
  • 1
Swift Dev Journal
  • 19,282
  • 4
  • 56
  • 66
  • I still hope this is not the only solution. After all, XCode already parses my sources, maybe there is some simpler way. Thanks for your answer. – Peter Štibraný Aug 06 '11 at 08:19
  • Xcode's Quick Help uses your installed documentation sets to display its contents. Unless you create and install a documentation set for your classes, all Quick Help displays is a link to the header file where you declared the class, method, or data member. Look at Xcode's symbol navigator. It shows your classes' methods and members. Choose View > Navigators > Show Symbol Navigator to open the symbol navigator. – Swift Dev Journal Aug 07 '11 at 18:53