Documenting in Xcode Dos and Donts Using Header

Documenting in Xcode: Do’s and Don’ts Using Header. Doc to make complete documentation as Html file. By Naveed Khalid

File Header Comment // // File Name. ext Project Name Created by <Author Name> on dd/mm/yyyy. Copyright 2014 (c) <Company Name>. All rights reserved.

Header. Doc Comment Header. Doc is a tool that you can run from the command-line. Basically it scans your files for comments made in a particular style. Following that particular style will help in documentation on the go! Which particular style?

Header. Doc Comment Three styles of comments that Header. Doc scans for: Option 1: /// Your documentation comment will go here Option 2: /** * Your documentation comment will go here */ Option 3: /*! * Your documentation comment will go here */

Header. Doc Comment These are similar to “normal” comments, except that there’s an extra / in option 1, and Three styles of comments that Header. Doc for: anscans extra character in the first line of options 2 Option 1: /// Your documentation comment will go here and 3 (* and !, respectively). Option 2: /** * Your documentation comment will go here */ Option 3: /*! * Your documentation comment will go here */

Best Way? For single line comments, use the triple forward slash syntax (///) For multiline comments, use the style used in Apple’s documentation (/*!)

Header. Doc Tags? A tag starts with the @ symbol and a keyword, followed by a space, and a string that contains a description relative to that keyword (such as @param foo). Top-Level Tags: These are tags that declare the type of thing you are commenting (Headers, classes, methods, etc). An example of a top-level tag is @typedef. Second-Level Tags: These tags help to give more detail about the specific thing you are commenting. Such as @brief, @abstract etc.

Some Second-level Tags @abstract A short string that briefly describes anything. This should not contain multiple lines @brief Equivalent to @abstract. Provided for better Doxygen compatibility. @discussion A block of text that describes a function, class, header, or data type in detail. @param The name and description of a parameter to a function @return Describes the return values expected from this function. Don't include if the return value is void @result Same as @return

Classes, Protocols, and Interfaces Example of @class tag in Objective-C /*! @class my. Class @inherits Base class @conforms List of protocol name those this class conforms to @discussion This is a discussion. It can span many lines or paragraphs. */ @interface my. Class : NSObject @end

Classes, Protocols, and Interfaces Example of @protocol tag in Objective-C /*! @protocol my. Protocol @discussion This is a discussion. It can span many lines or paragraphs. */ @protocol my. Protocol @end

Classes, Protocols, and Interfaces Example of @category tag in Objective-C /*! @category my. Main. Class(my. Category) @discussion This is a discussion. It can span many lines or paragraphs. */ @interface my. Main. Class(my. Category) @end

Documenting Methods /*! * @discussion A really simple way to calculate the sum of two numbers. * @param first. Number An NSInteger to be used in the summation of two numbers * @param second. Number The second half of the equation. * @return The sum of the two numbers passed in. */

Warnings To inform about add a @warning tag. Add the following text just above the @return tag: * @warning Please make note that this method is only good for adding non-negative numbers.

Documenting Property Example of @property tag /*! @property Property name @brief The View. Controller class' car object. */

Documenting Variables Example of @var tag /*! @var we_are_root @abstract Tells whether this device is the root power domain @discussion TRUE if this device is the root power domain. For more information on power domains. . */ bool we_are_root;

Documenting Constants Example of @const tag /*! @const k. CFType. Array. Call. Backs @abstract Predefined CFArray. Call. Backs structure containing a set of callbacks appropriate. . . @discussion Extended discussion goes here. */ const CFArray. Call. Backs k. CFType. Array. Call. Backs;

Documenting Enumeration Example of @enum tag /*! @enum Enumeration name @discussion Detail description of enum */

Documenting Enumeration /*! * @typedef Old. Car. Type * @brief A list of older car types. * @constant Old. Car. Type. Model. T A cool old car. * @constant Old. Car. Type. Model. A A sophisticated old car. */ typedef enum { Old. Car. Type. Model. T, Old. Car. Type. Model. A } Old. Car. Type;

Documenting Enumeration typedef enum { /// A cool, old car. Old. Car. Type. Model. T, /// A sophisticated older car. Old. Car. Type. Model. A } Old. Car. Type;

Adding Formatted Code /*! * @brief The car will drive, and then execute the drive block * @param completion A drive. Completion block * @code [car drive. Car. With. Completion: ^(CGFloat distance){ NSLog(@"Distance driven %f", distance); }]; */

Other Comments // FIXME: This is broken // !!!: Holy cow, it should be checked! // ? ? ? : Perhaps check if the block is not nil first?

Code Snippet for comments /*! * @discussion <#description#> * @param <#param description#> * @return <#return description#> */

Finalizing: Creating Html Open terminal cd /path/to/your/folder headerdoc 2 html -o ~/Desktop/destination. Folder source. Folder/ Now to create a Master TOC cd ~/Desktop/documentation gatherheaderdoc.