How do you document a description for a custom class in Objective-C/Swift?

Question

I know you can use /// (triple slash) to comment variables and even use /** for doxygen style comments on functions and the like, but is there a way to document a custom class itself? So if someone were to option-click it in Xcode there would be a description?

Answer 1

I had a same issue and found the solution.

1. You use @file tag(or \\file tag) when you want to make a comment for custom class with Doxygen. (This is a recommended way in Doxygen Document site, but it is often overlooked.)

2. write a comment you want with tag

That's it.

For example :

/*!
@file CustomViewController.h
*/
#import <UIKit/UIKit.h>

/*!
 @brief The CustomViewController Header file

 @discussion CustomVC

 @superclass SuperClass: UIViewController
 @classdesign    No special design is applied here.
 @coclass    AppDelegate
 @helps It helps no other classes.
 @helper    No helper exists for this class.
 @author dakeshi
 @version 1.0
*/

@interface CustomViewController : UIViewController

** I tested this code with Xcode 6.2

You can recognize the @file tag is seperated. Doxygen can not generate document what I want to if I moved the @file tag in the second comment block. It's only working perfectly @file tag is described alone.(I can not find the reason yet.)

You can use @class, @protocol tag in second comment block, but you need to use it very carefully. Some tags have to use with newline.(eg @discussion, @class) because Apple has reserved keywords that are same name of some tags). If you use @class tag without newline in above example, you just could see a normal apple documentation about UIViewController.

Answer 2

You can document with different ways like

/*!
 * @discussion <#description#>
 * @param <#param description#>
 * @return <#return description#>
 */

See detailed description of @discussion key words and how to use these comments fastly using code snippets in below link

http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial