Xcode headerdoc tutorial (2)

Code snippets makes everything easier:

This is really easy, isn't it? But is it simpler?

This site has introduced code snippets, please refer to here.

Code snippets plays the role of an unknown hero in xcode. An snippet is a reusable code block (stored in the snippet library ). Snippets can even contain placeholders that need to be filled. What does this mean? You can use snipppet to document your website. This is really a good note.

In mathapi. H, add the following content to the original comment:

 

/*! * @ Discussion <# description #> * @ Param <# Param description #> * @ Return <# Return description #> */

 

Note: When you paste the above Code, the content between "<#>" will become a token, And you can switch back and forth between tokens through the tab key. This is like the Automatic completion function you use when writing code.

Next we will use a tip. Open the codesnippets library checker window in the utilities panel, select the comment block, and drag it to the code snippet library window (from a token such as <# description #> ):

A window will pop up asking you to enter some information about snippet and create an automatic shortcut. You can write code in it. Follow these steps:

 

 

You can edit snippet code or shortcuts at any time. You can edit snippet or create a new snippet. To edit snippet, click snippet in the code snippet library, and then click the edit button.

To make your snippet take effect, first Delete the original comment, place the mouse in front of addnumber: tonumber: + of the method, enter doccomment, and press Enter. Your snippet will automatically appear. Move the three tokens using the tab key and fill them with the tab key. The final documented results are as follows:

/*! * @ Discussion a really simple way to calculate the sum of two numbers. * @ Param firstnumber an nsinteger to be used in the summation of two numbers. * @ Param secondnumber the second half of the equation. * @ Warning please make note that this method is only good for adding non-negative numbers. * @ Return the sum of the two numbers passed in. */

Of course, you need to manually write 2nd @ Param tags and @ warning tags, but snippet still saves a lot of time.

You can continue. Look, what is documented!

Docization of typedefs

OpenCar. hBefore the class, there are still some things to document. There is an ns_enum, that is, typedef Enum, a block, several attributes, and an empty method. Don't be discouraged. It's easy, every minute.

Do you still remember the @ typedef tag? This top-level label is a little special. It can comment on something like typedef Enum or typedef struct. Based on the object you comment on, it will contain Level 2 labels related to the defined type.

Taking Enum as an example, it will contain the @ constant tag for each constant (for struct, it will be the @ field tag ).

Find the enum oldcartype. It contains two constants used in classical cars. On the typedef declaration, replace the original Annotation:

/*! * @ Typedef oldcartype * @ Brief a list of older car types. * @ Constant oldcartypemodelt a cool old car. * @ Constant oldcartypemodela a sophisticated old car. */ Typedef Enum { Oldcartypemodelt, Oldcartypemodela } Oldcartype;

Compile, and then use Alt + left button on oldcartype. You will see the content of the @ brief tag. Now, ALT + left button on oldcartypemodela. Have you seen your comments? Tragedy happened.

Don't worry, you can still find what you want-we must put the right thing in the right place. Add the following annotations to Enum:

But fear not, you canstill get your information where you need it-we 've ve got the trusty tripleforward slash in our tool belt. Add the comments to the enum like you see here:

Typedef Enum { /// A cool, old car. Oldcartypemodelt, /// A sophisticated older car. Oldcartypemodela } Oldcartype;

Compile, ALT + Left click to view your comments.

There is only one ns_enum in this class, so you can document it on your own. The constant has been commented out. You only need to make an overall comment on the entire ns_enum.

/*! * @ Typedefcartype

* @ Brief alist of newer car types.

* @ Constantcartypehatchback hatchbacks are fun, but small.

* @ Constantcartypesedan sedans shocould have enough room to put your kids, and your golfclubs

* @ Constantcartypeestate estate cars shocould hold your kids, groceries, sport equipment, etc.

* @ Constantcartypesport sport cars shoshould be fast, fun, and hard on the back.

*/

 

Note:This Enum is declared through a macro. xcode cannot fully support the same document features as typedef Enum, although ns_enum is actually a recommended method for declaring enums. This may change in the future, but not yet.

Now let's document the cartype attribute.

/// Indicates the kind of car as enumerated in the "cartype" ns_enum @ Property (nonatomic, assign) cartype;

Compile and ALT + left button on the cartype variable name.

Continue to document the typedef block. See:

/*! * @ Brief a block that makes the car drive. * @ Param distance the distance is equal to a distance driven when the block is ready to execute. it cocould be miles, or kilometers, but not both. just pick one and stick with it.;] */Typedef void (^ drivecompletion) (cgfloat distance );

The docalization of the typedef block is not much different from the previous one. It includes:

• A @ brief tag briefly describes the role of this block.
• A @ Param label indicates the parameters to be passed when a block is called.

Add the formatting code to the document

Sometimes it is better for a programmer to tell him how to use a method.

For example, drivecarwithcomplete of the car class: method.

This method uses blocks as parameters, because blocks are generally difficult for beginners, so it is best to tell programmers how to use them.

This requires the @ code tag. Add the following content before the drivecarwithcompletion method declaration:

/*! * @ Brief the car will drive, and then execute the drive Block * @ Param completion a drivecompletion Block * @ Code [Car drivecarwithcompletion: ^ (cgfloat distance) {nslog (@ "distance driven % F", distance);}]; */

Compile and use the Alt + left button on the method name. As shown in.

Check document

You learned how to add comments. If xcode can help you check your work, just like xcode will automatically check the syntax errors in the code, isn't it better? There is good news. Clang has a flag called "clang_warn_documentation_comments", which can be used to check comments in headerdoc format.

Open documentationexamplesProject Settings,Click build settings and findDocumentationcomments, Set the valueYes.