Xcode headerdoc tutorial (3)

Open mathapi. H, change the parameter name of the First @ Param tag from firstnumber to thirdnumber, and compile.

There was a warning, and even a suggestion for modification. It does not affect anything, but helps to check for errors in the document.

Special notes

Xcode also supports several special annotations, which are very useful to you or those who use your code.

Open car. M and add the following comments before calling the completion block in drivecarwithcompletion: method:

// Fixme: This is broken //!!! : Holy cow, it shoshould be checked! //??? : Perhaps check if the block is not nil first?

Note 3 appears:

• Fixme: Correction is required somewhere
• !!!: Pay attention to a specific place.
• ???: There is a problem in the Code, or the code is suspicious.

These annotations not only help you browse the code, but also display them in xcode's jump bar. Click the jump bar, as shown in:

You will see the three annotations in bold:

At this point, you have mastered how to document the project. Take some time to operate on other properties and methods of the project, and add some of your own things. See what happens when you change something in the comment block or delete a tag. This will let you understand how the comment format affects the document.

Use headerdoc2html to Create HTML documents

Documentation is completed by a headerdoc tool. When xcode is installed, it has been installed. In addition to interpreting your comments, displaying a pop-up menu, and displaying the comments in quick help, you can also create HTML, XML, and online help manuals after you document them.

This section describes how to create an HTML file. If you are interested in using headerdoc to create online documents, please refer to headerdoc user guide.

Open the terminal and go to the documentationexamples project directory:

CD/path/to/Your/folder

Make sure that the path contains the xcodeproject file ("documentationexamples. xcodeproj ").

Run the following command to create an HTML document:

Headerdoc2html-O ~ /Desktop/documentation documentationexamples/

At this time, the terminal will have a lot of output. After creation, return to the desktop and a directory named documentation appears. Double-click to open the car_h directory and open index.html. Cool-you have a beautiful document!

 

Let's explain it. The headerdoc2html script has two parameters:

So what justhappened? Well, you ranHeaderdoc2htmlScript with 2 options:

• -O ~ /Desktop/documentation-this parameter specifies the output HTML file path-the documentation directory of the desktop.
• Documentationexamples/-this parameter specifies that the source file to be parsed is located inDocumentationexamplesDirectory (excluding other directories under the project directory because they do not contain source code)

Problem: the latest version of headerdoc2html has a problem. After Google Chrome is used to open index.html, the directory on the left is abnormal, but Safari is normal. In addition, you will notice that your previous comments on the cartype property are not displayed. It seems that the latest version of headerdoc2html cannot parse the // class annotation correctly. You can use /*! Type annotation.

This is cool, but you can proceed further. In addition to entering the output directory manually for navigation, headerdoc also creates a Home Directory Index. Return to the terminal, navigate to the new documentation directory, and enter:

Cd ~ /Desktop/Documentation

Run the following command to create a Content Index:

Gatherheaderdoc.

GatherheaderdocAutomatically searches for directories and creates an index for the. Directory (indicating the current directory. Use the Finder to open the documentation directory. You will find an extra mastertoc.html file. Open it to list links to all documented properties, methods, enumerations, and blocks.

You can put all HTML files on the web server, and then everyone can access your documents!

Vv1_enter-xcode

 

The final content is vv1_enter-xcode, a third-party xcode plug-in, which makes your document chemical work easier than using the code snippet introduced earlier.

First, download the plug-in from GitHub.

All you need to do is open the project and build it. It automatically installs the plug-in~ /Library/applicationsupport/developer/shared/xcode/plug-insDirectory.

Restart xcode. Open the documentationexamples project again. In mathapi. H, delete the comment block of the addnumber: tonumber method, and enter:

///

Vv1_enter-xcode will automatically create annotation blocks, including all necessary @ Param labels and automatically complete token.

Is it awesome?

Open car. h and delete the annotation of ns_enum cartype and the annotation of each constant. On the ns_enum declaration, enter:

///

This time, it will create the discussion tag on the enum, and even add the necessary comments to each constant!

Vv1_enter-xcode makes your life easier. If you want to customize vv1_enter-xcode, in xcode, useWindow> vv1_enterMenu.

Here, you can change the automatically completed keywords, annotation style, and others. You can customize vv1_enter-xcode. Vv1_enter-xcode saves a lot of time!

What to do next?

The final sample project is downloaded here.

Document in your own code. Write your own code snippet and use vvdocumentor. Try different styles and find your favorites and use them in your actual work.

Undoubtedly, the apple headerdoc User Guide is also a good learning document for you.

If you have any questions or suggestions, please let me know in the following discussion.