The Objective-C specification notes experience -- also compatible with appledoc

Recommended for you: Get network issues from WhatsUp Gold. Not end users.

Author: zyl910

  Hand written document is a chore, but fortunately there are special tool to extract the comments to generate documentation from the source. For Objective-C, the best use of the tool is appledoc and doxygen. But these two tools for the annotation require slightly different. So I after a fumble, find a compatible with these two tools notes written.

  Tool——

appledoc: Simple and convenient, suitable for generating Apple style of the HTML document, and integrated directly into the Xcode help (docset). Official website .

doxygen: Powerful, suitable for generating HTML and PDF documents. Official website .

  System environment——

Mac OS X Lion 10.7.5

Xcode 4.6.2

appledoc 2.1

doxygen 1.8.4

MacTeX-2012

First, note writing

  Tip: this chapter is reference content, relatively dry. Please according to the need to read——

For those who want to study the notes written, read before the 4 day on the line,

To comprehensively study the appledoc and Doxygen are compatible with notes written, read before the 6 day on the line,

For both want to use appledoc, and want to use the Doxygen enhancement effect, please read all day.

1.1 forms of glosses

  Standard C/C++ comments in the form with “ //” single line comments and &ldquo form; / * */” forms of multi line comment the two.

  The document notes appledoc and Doxygen is their variety, there are a variety of forms. For example, appledoc and Doxygen were compatible with the comment form the following 7——

/// Single line comment.

/// Single line comment spreading
/// over multiple lines.

/** Single line comment. */

/** Single line comment spreading
 * over multiple lines.
 */

/** Single line comment spreading
 over multiple lines. No star.
 */

/*! Single line comment. */

/*! Single line comment spreading
 over multiple lines.
 */

  Although appledoc and Doxygen support. But usually when you write code, in order to avoid style cluttered visual pollution, should be fixed using the annotation form.

1.1.1 single line comment

  In many cases only need to write a brief description is enough, then it is best to use a single line comment. The recommended format for——

/// A brief description.

  Appledoc and Doxygen are single “ ///” note recognition for a brief description. Compatibility is very high.

  Remarks——

1) The best English text to an end (.). This helps code reading, clearly that the text has ended, but also help to avoid the garbled when the newline loss problem.

2) Don't continuous multi line using the “ ///”. Doxygen by default, the multi line “ ///” as described in detail, and no brief comments. Although you can modify the Doxygen configuration to solve the problem, but the multi line “ ///” itself is contrary to “ &rdquo is briefly described; this intention.

1.1.2 multi line comment

  When the need to write a detailed description, then you need to use multiline comments. The recommended format for——

/** A brief description.
 *
 * Detailed description or other.
 */

  For appledoc and JAVADOC_AUTOBRIEF parameters of Doxygen, all of them will be annotated in the first paragraph recognition is described briefly, and then segment identification later for detailed description.

  In fact, the Doxygen standard for multi line comments——

/**
 * @A brief description of brief.
 *
 * Detailed description or other.
 */

  Unfortunately, appledoc support for the @brief instruction defects in — — @brief cannot appear, protocol note, will lead to further loss of content. @brief multi line comments can only be safely used in attribute, method of note.

  Remarks——

1) Multi line comments in “ ” concept, content is empty rows as piecewise basis. If there is no blank line between words, will be continuous content link up to form a line.

2) If the asterisk omit intermediate row column (*), appledoc and Doxygen can also identify. When considering the indent, beautiful, compatibility, or suggestions don't omit the asterisk.

1.1.3 note (Doxygen only)

  In the enumeration members, annotation structure type, in order to make the content more compact, we generally like to write comments at the end of the line.

  Unfortunately, currently only support Doxygen note, but appledoc does not support.

  Doxygen supports the following 4 note——

/**<Note 1 appledoc does not support will become the next note, Doxygen support, according to the English stop briefly describe the automatic segmentation and described in detail. */
/*!<Note 2 appledoc does not support will become the next note, Doxygen support, will be as described in detail, and the lack of a brief description. */
///<Note 3 appledoc does not support will become the next note, Doxygen support.
//!<Note 4 appledoc does not support will be ignored, Doxygen support.

  In order to avoid appledoc error will note as a comment, but we recommend fourth note — — to “ <” //! The comments at the beginning.

Class 1.2 (protocol, classification) comments

  For the class of (protocol, classification), generally only need to write a brief description on the line, then you can use a single line comment——

/// Document A.
@interface DocA : NSObject

  When you need to leave the detailed description, can be changed into multi line comment——

/** Document B.
 *
 * A detailed description of the document B.
 */
@interface DocB : NSObject

The 1.3 attribute annotations

  The property, originally the use of note is the best, can make the content more compact. Unfortunately, the appledoc does not support the end of line comments. Had to settle for second best, choice of single line comments.——

/// Numerical attributes.
@property (nonatomic,assign) NSInteger num;

  When you need to leave the detailed description, can be changed into multi line comment——

/**
 * @The brief string attributes.
 *
 * A detailed description of attributes.
 */
@property (nonatomic,strong) NSString* str;

1.4 methods of annotation

  For none of the parameters, simple method return value, you can use a single line comment——

/// Simple method.
- (void)someMethod;

  If the method has parameters or return values, then we must use multiline comments.——

/**
 * @Methods brief with integer parameter.
 *
 * @Param value values.
 *
 * @Return returns value.
 */
- (int)someMethodByInt:(int)value;

  Instructions——

@param <name> <description>: Parameter description.

@return <description>: The return value is described.

  Because annotations need to fill in more content (parameter list and return value), so now there are many plugins can help generating method, notes, and these plugins are generally use the @brief multi line comment. For example, in the reference "Xcode4 fast Doxygen comments — graphic tutorial concise (3 minutes after the great) .

  In some cases, we also need a complete anomaly in comments, see, warning information——

/**
 * @Methods brief with string parameters.
 *
 * @Param value values.
 *
 * @Return returns value.
 *
 * @Abnormal exception NSException may throw.
 *
 * @see someMethod
 * @see someMethodByInt:
 * @Warning warning: appledoc is shown as a blue background, Doxygen appears as a red bar.
 * @Defect: bug appledoc appears as a yellow background, Doxygen display for the green bars.
 */
- (NSString*)someMethodByStr:(NSString*)value;

  Instructions——

@exception <name> <description>: Abnormal description.

@see <name>: See. Specific usage see 1.5.2 @see, @sa (see).

@warning <text>: Warning.

@bug <text>: Warning.

1.5 appledoc,Doxygen support command

  Instruction to “ @” at the beginning, can also use “ \” symbols at the beginning. If you want to use &ldquo in the text; @” “ \”, symbols, can use “ \” escape characters, such as “ \@” “ \”, etc.

The 1.5.1 instruction list

  The instructions are called &ldquo in appledoc; Directive”, and called in Doxygen“Command”.

  Appledoc did not specifically reference document, only in the "Comments formatting style" to a few simple examples.

  Doxygen instruction set reference document in detail, see Special Commands .

  After the test, I found the following instructions are effective in appledoc and Doxygen——

@brief <title>: A brief comment. Appledoc only in the attribute, method is effective, invalid agreement, will cause the failure of class, the following analysis.

@param <name> <description>: Parameter description.

@return <description>: The return value is described.

@exception <name> <description>: Abnormal description.

@see <name>: See.

@sa <name>: See.@see.

@warning <text>: Warning.

@bug <text>: Warning.

@name <title>: The group name. To give members group, Tasks area is in the document subcategories.

1.5.2 @see,@SA (see)

  See instruction format——

@see <name>

@sa <name>

  The appledoc and Doxygen are compatible with the context, <name> for the——

1) The current class (or agreement) property or method of. (note that the Objective-C method signature is written, usually “ the method name: 2:. &rdquo. 1: parameter; format)

2) The class name (or agreement). (note that appledoc does not support the current class)

  Although appledoc and Doxygen are supported. See Synonyms at “ other classes or protocol in &rdquo, but their members; different ways of writing, but are not compatible with each other——

appledoc: Using the Objective-C Message Syntax, “ [class member]&rdquo format;.

doxygen: The use of traditional object member access syntax, “ class. Members of the &rdquo format;.

  Pay attention to the instructions and @brief instructions have the same problem — — appledoc only in the attribute, method is effective, invalid agreement, will cause the failure of class, following content analysis. There were two kinds of treatment strategies——

1) Will see instructions on the back annotation, avoid the loss of content, and can ensure that in Doxygen effect.

2) Use the links to replace. See the 1.6.4 link.

1.6 appledoc,Doxygen support format

  Plain text without formatting and look hard, to format, in order to improve the document organization and performance. Appledoc and Doxygen have their own set of conventions——

Appledoc can refer to Comments formatting style .

Doxygen can refer to Markdown support .

  This section will introduce appledoc and Doxygen both supported format.

1.6.1 code text

  Sometimes the need to introduce a piece of code in a paragraph, then can use the accents (`) that a section of code to wrap up. For example——

/**
 * Refer to short code, such as `someMethodByStr:` .
 */

1.6.2 code block

  A block of code is applicable to the need to place more lines of code in the annotation of the situation. The specific measures are in front of each line with a tab character, for example——

/**
 * The sample code:
 *
 *     int sum=0;
 *     for(int i=1; i<=10; ++i) {
 *         sum += i;
 *     }
 */


  Because of space and Tab characters are displayed as blank, is not easy to distinguish. So using <space> <tab> expression, spaces and tab character, the actual annotation——

/**
<space>*<space>The sample code:
<space>*
<space>*<space><tab>int sum=0;
<space>*<space><tab>for(int i=1; i<=10; ++i) {
<space>*<space><tab><tab>sum += i;
<space>*<space><tab>}
<space>*/

  The asterisk notes of each row start (*) and content must be used between the blank characters are separated, so usually with spaces or a tab character. But in the use of a code block, in order to avoid misjudgment of the Tab character, the best content strictly to “ <space> <tab> ” at the beginning (both lines in “ <space> *<space> <tab> ” at the beginning).

  Remarks——

1) Pay attention to the concept of a code block, between before and after the text should open a line.

2) Appledoc and Doxygen also supports the 4 spaces as a tab character. But the 4 character input, maintenance will be more laborious, does not recommend the use of.

1.6.2.1 Xcode in the input code block

  In Xcode, when you press the Tab key, character spaces will automatically integrate the front, resulting in a code block layout failure. It is recommended to paste in a multi line comments in code, and then enter the &ldquo in line; *<space> <tab> ”. Examples are as follows——

  First of all, the first note is this——

/**
 * @A brief description of brief.
 *
 * Detailed description or other.
 */

  The first step, paste the code in a multi line comment, note that Xcode will automatically typesetting to paste the content, add a space in front of each line——

/**
 * @A brief description of brief.
 *
 * Detailed description or other.
 int sum=0;
 for(int i=1; i<=10; ++i) {
     sum += i;
 }
 */

  The second step, to complete the. Copy the “ *<space> <tab> ”, for that code previously paste, paste in second characters in each line, to form the “ <space> *<space> <tab> ” at the beginning of the code block format——

/**
 * @A brief description of brief.
 *
 * Detailed description or other.
 *     int sum=0;
 *     for(int i=1; i<=10; ++i) {
 *         sum += i;
 *     }
 */

  The third step, Xiu mei. Increasing the blank lines, increase “ Code: ” line, suggesting here is the code——

/**
 * @A brief description of brief.
 *
 * Detailed description or other.
 *
 * Code:
 *
 *     int sum=0;
 *     for(int i=1; i<=10; ++i) {
 *         sum += i;
 *     }
 */

The 1.6.3 list

1.6.3.1 unordered list

  In the beginning of each line using “ -” “, +” or “ *” character, can create unordered list. For example——

/**
 * Unordered list:
 *
 * - abc
 * - xyz
 * - rgb
 */

1.6.3.2 ordered list

  The use of digital and decimal point, can create an ordered list. For example——

/**
 * The ordered list:
 *
 * 1. first.
 * 2. second.
 * 3. third.
 */

1.6.3.3 multilevel list

  Using the tab character with the use of unordered list or a multilevel list, you can create a multilevel list. For example——

/**
 * A multilevel list:
 *
 * - xyz
 *    - x
 *    - y
 *    - z
 * - rgb
 *    - red
 *        1. first.
 *            1. alpha.
 *            2. beta.
 *        2. second.
 *        3. third.
 *    - green
 *    - blue
 */

The 1.6.4 link

  There are three types of links——

1) The direct link. The format for the <link>. Will link address directly as text to display.

2) Text link. The format for the [text] (<link>). The text using the custom as the link name.

3) Cross reference links. More complex, and difficult to be compatible with appledoc and Doxygen, this paper does not discuss.

1.6.4.1 Url

  Write URL in comments directly will automatically create a link, for example——

/**
 * http://appledoc.gentlebytes.com/ : Write a URL link.
 */

  Can also use text links form——

/**
 * [Doxygen](http://www.stack.nl/~dimitri/doxygen/) : Provides the text for the link.
 */

The 1.6.4.2 class and protocol

  In the annotations to write directly on the class (or agreement), and pay attention to both sides of space, appledoc and Doxygen will be automatically generated to the class (or agreement) link. For example——

/**
 * DocA: the class.
 */

  But for text links, appledoc and Doxygen are different——

/**
 * - [B] (DocB) document: the text of the link category (appledoc only).
 * - [document B] (@ref DocB): to provide \@ref text links (only doxygen. appledoc will use \@ref as text and generate error link).
 */

  Recommendations or to use direct link.

The 1.6.4.3 property and method (appledoc only)

  If there is a [MEMBER] comment, appledoc automatically creates the link, but Doxygen does not support this function.

  If a property or method of the current class name comment, appledoc automatically creates the link, but Doxygen does not support this function. But appledoc also has Bug— — if in the same piece of note in [MEMBER], so the current class property or method of link failure.

  So unstable function or not.

The Doxygen annotation example 1.7 commonly used

  The Doxygen annotation of a see things in a blur, here introduces several writing.

1.7.1 file header

  General format——

/**
 * @file    MyDocViewController.h
 * @The brief homepage.
 * @author    [zyl910](http://www.cnblogs.com/zyl910/)
 * @version    1.0
 * @date    2013-06-07
 *
 * # Update (log)
 *
 * [2013-06-07] <zyl910> v1.0
 *
 * + v1.0 release.
 *
 */

  Instructions——

@file [<name>]: The file name.

@author <list of authors>: Author. Here I use link, see the 1.6.4 link.

@version <version number>: The version number.

@date <date description>: The date.

  In order to well number (#) at the beginning of the line that is the title. If there are 1 well number (#), that is a title. If there are 2 well number (##), said two heading levels, and so on.

The 1.7.2 enumeration, structure, combined with typedef

  For enumeration, structure, union types, and can be used for single line or multi line comment. For its members, recommend the use of note. For example——

/// The Objective-C documentation tools Mei Ju (Mei Ju, Doxygen).
typedef enum _ObjCDocToolEnum{
    ObjCDocToolEnumAppleDoc = 1,    //!<AppleDoc. http://appledoc.gentlebytes.com/ .
    ObjCDocToolEnumDoxygen,    //!<Doxygen. http://www.stack.nl/~dimitri/doxygen/ .
}ObjCDocToolEnum;


/** Integer rectangle (structure, Doxygen only).
 *
 * A detailed description of the structure.
 */
typedef struct _RectInt {
    int x;    //!<The abscissa.
    int y;    //!<The ordinate.
    int width;    //!<Width.
    int height;    //!<Height.
}RectInt, *PRectInt;    //!<Pointer to integer rectangle.
typedef const RectInt* PCRectInt;    //!<Integer rectangular constant pointer.


/// Floating point number of bytes (consortium, Doxygen only).
typedef union _FloatByte {
    float f;    //!<Single precision floating point number.
    unsigned char bytes[4];    //!<4 bytes.
} FloatByte;

   Note note of a comment, so be sure to use a semicolon (;) or a comma (,) that the member is defined, and then write a note. Including the last member.

  In the definition of the structure, the general also needs to define its associated pointer types and constants pointer types——

Definition of a pointer type, can be written together with the definition of the structure, characteristic of the note to note.

Defines a constant pointer types, need to write a separate line of typedef, and the use of note.

The 1.7.3 macro

  For a simple macro constant form, recommend the use of note. For example——

#define BUFSIZE    100    //!<The buffer size (simple macros, Doxygen only).

  The parameters of the macro, refer to &ldquo for ” note; write a multi line comment. For example——

/**
 *    @The minimum value of brief (parameter to the macro, Doxygen only).
 *
 *    @Param a a.
 *    @Param B B.
 *
 *    @Return returns the minimum value of the two.
 */
#define min(a,b)    ( ((a)<(b)) ? (a) : (b) )

A pointer to a 1.7.4 function and a function(Block Objects)

  For function pointers and block function, also can refer to “ method &rdquo write notes; multi line comment. For example——

/**
 *    @Action brief callback function.
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 */
typedef void (*ActionCallback)(void* sender, void* userdata);


/**
 *    @The brief action block function.
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 */
typedef void (^ActionHandler)(id sender, id userdata);

1.7.5 member variables

  For the member variable, recommend the use of note. For example——

@interface MyDocViewController : UIViewController {
    @private
    int _privateInt;    //!<Private member variables (only Doxygen EXTRACT_PRIVATE logo, can be classified as “ Private property”).
    
    @protected
    int _protectedInt;    //!<Protected member variables (Doxygen only, can be classified as “ Protected property”).
    id<MyDocDelegate> _delegate;    //!<The delegate variable.
    
    @package
    int _packageInt;    //!<Package member variables (Doxygen only, can be classified as “ Protected property”).
    
    @public
    int _publicInt;    //!<The public member variable (Doxygen only, can be classified as “ Public property”).
}

Two, code walkthrough

  Front said a lot of theoretical knowledge, now create a project to drill.

  Open the Xcode, create a new named “ MyDoc” “ Single View Application” iOS project.

  Then open the MyDocViewController.h, practice notes inside.

  All the code——

/**
 * @file    MyDocViewController.h
 * @The brief homepage.
 * @author    [zyl910](http://www.cnblogs.com/zyl910/)
 * @version    1.0
 * @date    2013-06-07
 *
 * # Update (log)
 *
 * [2013-06-07] <zyl910> v1.0
 *
 * + v1.0 release.
 *
 */

#import <UIKit/UIKit.h>


#define BUFSIZE    100    //!<The buffer size (simple macros, Doxygen only).

/**
 *    @The minimum value of brief (parameter to the macro, Doxygen only).
 *
 *    @Param a a.
 *    @Param B B.
 *
 *    @Return returns the minimum value of the two.
 */
#define min(a,b)    ( ((a)<(b)) ? (a) : (b) )


/// The Objective-C documentation tools Mei Ju (Mei Ju, Doxygen).
typedef enum _ObjCDocToolEnum{
    ObjCDocToolEnumAppleDoc = 1,    //!<AppleDoc. http://appledoc.gentlebytes.com/ .
    ObjCDocToolEnumDoxygen,    //!<Doxygen. http://www.stack.nl/~dimitri/doxygen/ .
}ObjCDocToolEnum;


/** Integer rectangle (structure, Doxygen only).
 *
 * A detailed description of the structure.
 */
typedef struct _RectInt {
    int x;    //!<The abscissa.
    int y;    //!<The ordinate.
    int width;    //!<Width.
    int height;    //!<Height.
}RectInt, *PRectInt;    //!<Pointer to integer rectangle.
typedef const RectInt* PCRectInt;    //!<Integer rectangular constant pointer.


/// Floating point number of bytes (consortium, Doxygen only).
typedef union _FloatByte {
    float f;    //!<Single precision floating point number.
    unsigned char bytes[4];    //!<4 bytes.
} FloatByte;


/**
 *    @Action brief callback function.
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 */
typedef void (*ActionCallback)(void* sender, void* userdata);


/**
 *    @The brief action block function.
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 */
typedef void (^ActionHandler)(id sender, id userdata);


/// Document A.
@interface DocA : NSObject
@end;

/** Document B.
 *
 * A detailed description of the document B.
 */
@interface DocB : NSObject
@end;


/// Objective-C document commissioned.
@protocol MyDocDelegate <NSObject>

@end

/** The main page.
 *
 * Page of the detailed description. 
 *
 * Refer to short code, such as `someMethodByStr:` .
 *
 * The sample code:
 *
 *     int sum=0;
 *     for(int i=1; i<=10; ++i) {
 *         sum += i;
 *     }
 *
 * Unordered list:
 *
 * - abc
 * - xyz
 * - rgb
 *
 * The ordered list:
 *
 * 1. first.
 * 2. second.
 * 3. third.
 *
 * A multilevel list:
 *
 * - xyz
 *    - x
 *    - y
 *    - z
 * - rgb
 *    - red
 *        1. first.
 *            1. alpha.
 *            2. beta.
 *        2. second.
 *        3. third.
 *    - green
 *    - blue
 *
 * The following is the only Doxygen visible content. Because appledoc does not support the type annotation in \@see tags (but in support of the attributes, methods using), will cause the following content dropped.
 *
 * @see str
 * @see someMethodByStr:
 * @see MyDocAppDelegate
 * @see [MyDocAppDelegate window]    // Only appledoc. Doxygen can only identify the class name.
 * @see [MyDocAppDelegate someMethodByFloat:]    // Only appledoc. Doxygen can only identify the class name.
 * @see MyDocAppDelegate.window    // Only doxygen. appledoc can only identify the class name.
 * @see MyDocAppDelegate.someMethodByFloat:    // Only doxygen. appledoc can only identify the class name.
 *
 * end.
 *
 */
@interface MyDocViewController : UIViewController {
    @private
    int _privateInt;    //!<Private member variables (only Doxygen EXTRACT_PRIVATE logo, can be classified as “ Private property”).
    
    @protected
    int _protectedInt;    //!<Protected member variables (Doxygen only, can be classified as “ Protected property”).
    id<MyDocDelegate> _delegate;    //!<The delegate variable.
    
    @package
    int _packageInt;    //!<Package member variables (Doxygen only, can be classified as “ Protected property”).
    
    @public
    int _publicInt;    //!<The public member variable (Doxygen only, can be classified as “ Public property”).
}

#pragma mark - property

/// Numerical attributes.
@property (nonatomic,assign) NSInteger num;

/** String attribute.
 *
 * A detailed description of attributes.
 */
@property (nonatomic,strong) NSString* str;


// Test note.
@property (nonatomic,strong) NSString* strend1;    /**<Note 1 appledoc does not support will become the next note, Doxygen support, according to the English full automatic segmentation is described in detail and describe it in detail. */
@property (nonatomic,strong) NSString* strend2;    /*!<Note 2 appledoc does not support will become the next note, Doxygen support, will be as described in detail, and the lack of a detailed description. */
@property (nonatomic,strong) NSString* strend3;    ///<Note 3 appledoc does not support will become the next note, Doxygen support.
@property (nonatomic,strong) NSString* strend4;    //!<Note 4 appledoc does not support will be ignored, Doxygen support.
@property (nonatomic,assign) int dummy;


/// The enumeration of the attributes.
@property (nonatomic, assign) ObjCDocToolEnum docTool;

/// Properties of the structure.
@property (nonatomic, assign) RectInt rectInt;

/// Attribute structure constant pointer.
@property (nonatomic, assign) PCRectInt prectInt;

/// Attribute combination.
@property (nonatomic, assign) FloatByte floatByte;

/// Entrust.
@property (nonatomic, strong) id<MyDocDelegate> delegate;


/** Link test.
 *
 * Link:
 *
 * - http://appledoc.gentlebytes.com/ : Write a URL link.
 * - [Doxygen](http://www.stack.nl/~dimitri/doxygen/) : Provides the text for the link.
 * MyDocDelegate: interface.
 * DocA: the class.
 * - [B] (DocB) document: the text of the link category (appledoc only).
 * - [document B] (@ref DocB): to provide \@ref text links (only doxygen. appledoc will use \@ref as text and generate error link).
 * - @ref DocB : \@The ref link (only doxygen. appledoc will use \@ref as text).
 *
 * @see str
 * @see someMethodByStr:
 * @see MyDocAppDelegate
 * @see [MyDocAppDelegate window]    // Only appledoc. Doxygen can only identify the class name.
 * @see [MyDocAppDelegate someMethodByFloat:]    // Only appledoc. Doxygen can only identify the class name.
 * @see MyDocAppDelegate.window    // Only doxygen. appledoc can only identify the class name.
 * @see MyDocAppDelegate.someMethodByFloat:    // Only doxygen. appledoc can only identify the class name.
 */
@property (nonatomic,strong) NSString* alink;

/** The local link test 1 (appledoc only).
 *
 * Link:
 *
 * STR: its properties.
 * SomeMethodByStr:: its method.
 * MyDocViewController: its class. // appledoc is not recognized.
 * MyDocAppDelegate: outside the class.
 */
@property (nonatomic,strong) NSString* alinklocal1;

/** The local link test 2 (appledoc only).
 *
 * As long as there \[class members \] form of link, the link will be effective.
 *
 * Link:
 *
 * STR: its properties.
 * SomeMethodByStr:: its method.
 * MyDocViewController: its class. // appledoc is not recognized.
 * MyDocAppDelegate: outside the class.
 * - [MyDocViewController str] : Its properties.
 */
@property (nonatomic,strong) NSString* alinklocal2;

/** The local link test 3 (appledoc only).
 *
 * As long as there \[class members \] form of link, the link will be effective.
 *
 * Link:
 *
 * STR: its properties.
 * SomeMethodByStr:: its method.
 * MyDocViewController: its class. // appledoc is not recognized.
 * MyDocAppDelegate: outside the class.
 * - [MyDocAppDelegate window] : The external attributes of a class.
 * - [MyDocAppDelegate someMethodByFloat:] : The methods of the class.
 */
@property (nonatomic,strong) NSString* alinklocal3;


#pragma mark - method

/// Simple method.
- (void)someMethod;

/**
 *    @Methods brief with integer parameter.
 *
 *    @Param value values.
 *
 *    @Return returns value.
 */
- (int)someMethodByInt:(int)value;

/**
 *    @Methods brief with string parameters.
 *
 *    @Param value values.
 *
 *    @Return returns value.
 *
 *    @Abnormal exception NSException may throw.
 *
 *    @see someMethod
 *    @see someMethodByInt:
 *    @Warning warning: appledoc is shown as a blue background, Doxygen appears as a red bar.
 *    @Defect: bug appledoc appears as a yellow background, Doxygen display for the green bars.
 */
- (NSString*)someMethodByStr:(NSString*)value;


/**
 *    @Brief has a static variable values of the methods of the class.
 *
 *    @Return returns the _classInt value of a static variable.
 */
+ (int)classInt;

@end


/// Page of the action related to the operation.
@interface MyDocViewController (Action)

/**
 *    @Brief call to action the callback function
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 *    @The param handler function.
 *
 *    @see callActionHandler:userdata:handler:
 */
- (void)callActionCallback:(void*)sender userdata:(void*)userdata handler:(ActionCallback)handler;

/**
 *    @Brief calls the action block function.
 *
 *    @Param sender sender.
 *    @Param UserData custom data.
 *    @The param handler function.
 *
 *    @see callActionCallback:userdata:handler:
 */
- (void)callActionHandler:(id)sender userdata:(id)userdata handler:(ActionHandler)handler;


@end

MyDocViewController.h


  Code written, you can use the appledoc or Doxygen document, as shown in the following two chapters.

Three, the use of appledoc to generate documentation(docset,html)

Installing appledoc 3.1

  Appledoc installation is very simple. Open a terminal, enter the following commands——

git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

The 3.2 generation docset

  For the latest version of the appledoc, which by default is to generate docset documents and integrated into the Xcode.

  Use the CD command in the terminal to enter the project folder, and then run the following command——

appledoc --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" .

  Note——

--output ./doc: Set output directory“./doc”.

--project-name objcdoc: Set the project name“objcdoc”.

--project-company "zyl910": A company called“zyl910”.

--company-id "cn.com.zyl910": Setting up company ID“cn.com.zyl910”.

.: The current directory.

  When the command is completed, open the Xcode Organizer Documentation, will find the new help document——

The 3.3 generation HTML

  When a HTML document, you can add“--no-create-docset”——

appledoc --no-create-docset --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" .

  When the command is completed, use the browser to open doc/html/index.html——

Four, the use of Doxygen to generate documentation(html,pdf)

Installing Doxygen 4.1

  Doxygen source code compiler installation and the installation of dmg. To save words, can choose to install dmg. Go to the Doxygen website () to download the latest dmg.

  DMG download, double-click the DMG loading, and then put into the application folder the.App file, and complete the installation.

The 4.2 generation HTML

  Doxygen has a graphical interface, can be opened through Launchpad.

  Choose the path in the project of step in 1.

  Step 2 default is Wizard-> the Project page, in which——

1) In the “ Project name” fill in the project name.

2) Check the “ Sacn recursively”, scanning of all sub folders.

3) In the “ Destination directory” complete document output directory. Here is my“docs”.

  Click on the middle of the “ Expert” switching Expert-> Project pages, in which the——

1) “ OUTPUT_LANGUAGE” to “ Chinese”, the use of simplified Chinese.

2) Check the “ JAVADOC_AUTOBRIEF” automatic annotation, first identified as a brief description.


  Click on the middle of the “ Run” switching the Run page, and then click the &ldquo Run button to generate documentation; doxygen”.

  When the document generation is completed, use the browser to open docs/html/index.html——

The 4.3 generation pdf

  By default Doxygen will be ready for the generation of pdf. Switch to the Wizard-> Project, will find it automatically check the “ LaTex” and“as intermediate format for hyperlinked PDF”.

  Doxygen itself does not directly output PDF file, but to generate the latex directory, which has a makefile file. If the system installed pdflatex, you can run &ldquo in the latex directory; make” command to generate a PDF file.

  How to install pdflatex? The Mac platform can be installed MacTeX. Open, Download   MacTeX.pkg (about 2.1GB). MacTeX.pkg download, double-click to run, according to the wizard to install.

  Environment installed, when running &ldquo in the latex directory; make” command to generate a PDF file, you'll find out — — pure English document can successfully generate PDF; which contains Chinese, unable to generate the PDF file.

  For latex layout, Doxygen actually have to do a lot of preparation, such as — — source file is the UTF-8 code, and use the default utf8 package. The theory is to support multi language.

  For Chinese, also need to load the CJKutf8 package, and configure the CJK environment. This can be used in Chinese.

  Use a text editor to open the docxygen generated latex in the directory refman.tex. Find the “ \begin{document}” this line, it is changed to——

\usepackage{CJKutf8} 
\begin{document}
\begin{CJK}{UTF8}{gbsn}

  Then find the “ \end{document}” this line, it is changed to——

\end{CJK} 
\end{document}

  Save and close the refman.tex.

  Then open a terminal, use the CD command to the latex directory, and then execute the &ldquo command; make”.

  After the execution is completed, will appear in this directory“refman.pdf”——

Reference——

[appledoc] Comments formatting style . Gentle Bytes.

[doxygen] Markdown support . doxygen.

[doxygen] Special Commands . doxygen.

Amazing Apple-like Documentation . 2011-11-29.

Document generation tools using Objective-C: appledoc "Tang Qiao., 2012-02-01.

On the way to see their own writing &ldquo description;”(AppleDoc) . Rainbird, 2012-11-25.

Using Doxygen as the Objective-C code to generate documentation . Seven's, 2011-11-20.

Xcode4 fast Doxygen comments — graphic tutorial concise (3 minutes after the great) . chukong-inc, 2012-05-16.

Use Doxygen to generate PDF documents in Chinese . zyl910, 2013-06-02.

Download the source code——

http://files.cnblogs.com/zyl910/objcdoc.zip


Recommended from our users: Dynamic Network Monitoring from WhatsUp Gold from IPSwitch. Free Download

Posted by Elliott at December 07, 2013 - 3:19 PM