iOS Development journal 23-xcode build API documentation (HEADERDOC)

Today Bo Master has a Xcode to generate API documentation requirements, encountered some difficulties, here and we share, hope to progress together.

Today the company and the customer handover source code, but the customer proposed not only the source code, but also the corresponding technical documentation, today the blogger will share with you, how to use Xcode to generate your technical documents.

There are three main tools for generating technical documentation: HEADERDOC, Doxygen and Appledoc. Headerdoc is Apple's official build tool, and the latter two are third-party tools. If the Xcode version is updated, you will need to reconfigure the third-party tools, while the personal feel is powerful, But the configuration is cumbersome, we recommend that you use Headerdoc.

To create a technical document, first of all, you have to have comments, no comments can not directly generate the document, you need to create a new pages, slowly handwriting it

The specification writes the good comment, one can let oneself not forget own code, two can produce the technical document directly, why not

Create a demo app with Objective-c

We start by creating a new project that uses OBJECTIVE-C, and this project will be used to test what we're going to see next. If you haven't done so, open Xcode and create a new project. Because we're not going to do a real demo app, check single View application.

In the next step, name the project as DOCDEMOOBJC, and in the Language drop-down menu, make sure the OBJECTIVE-C option is selected.

Documentation details

As you know, the simplest way to write a note in objective-c is to use two slashes, as shown:

1	// This is a comment.

You can (and must) place your comments as above to distinguish each part. But when it comes to code commenting on a document, I'm definitely not referring to the above comment. It certainly doesn't make sense if the entire tutorial is focused on this. Commenting on a document means using special keywords, also called tags, to write comments in a structured way, using special symbols to mark the annotation area, so the compiler can perfectly understand the process. There are only a few simple rules to follow. All the results of the above actions are that your Notes document can be displayed in three different places:

1. In the quick help Inspector of the utilities panel.

2. When you press the option key and then click on the method, class or property name, the Help menu pops up in the popup.

3. In the code implementation pop-up box.

In addition, the appropriate code comments allow you to use numerous tools to create complete HTML documents for your application, such as the Headerdoc. These two will be mentioned later, and you will see how I have just said.

Remember above, it's time to step closer. There are three possible ways to mark a Comment document area when writing code using OBJECTIVE-C:

1. Include your comments in the/**–*/block.

2. Include your comments in the/*! In the –*/block.

3. Comment Lines starting with three slash////

In this tutorial example we will write our annotated document in the second way. I chose it for two reasons: first, it is the only format that can be recognized by Headerdoc, and if the comment block does not start with it, the help page will not be generated. Second, although Doxygen prefers the first format, it can also recognize the second type. Therefore, the second format will work in both ways. The third format is usually used when commenting on a line, such as a property value, so, we persist in the second format.

Now, when writing an annotated document, you can use a specific key value (or label). Tags are divided into two categories: the first is the top level tag, which can be used to specify which type of code is commented, such as class, struct, file, and so on. Note that the top level label is not required, but it will certainly help the export tool (for example, Headerdoc) to create better results. The second is the second level tag, which specifies the details of each comment document block. This type of tag is exactly what you need, because each defines another part of the annotated document.

Below I have given the most important second level label, but note that this is not all. We'll see some top level labels later. What I have listed here is the most commonly used:

• @brief: use it to write short descriptive information about the method, property, class, file, struct, or enum you are documenting.

• @discussion: use it to write a detailed description. You can add line breaks if you want.

• @param: Through it you can describe the parameter information for a method or function. You can use multiple such tags.

• @return: use it to create a return value for a method or function.

• @see: use it to indicate other relevant method or function. You can use multiple such tags.

• @sa: Similar to the previous article.

• @code: with this tag, you can embed code snippets in your document. When viewing a document in Help inspector, the code is displayed in a different font in a special box. Always remember to use @endcode tags at the end of the code you write.

• @remark: When writing a document, use it to emphasize anything special about the code.

You can find a list of all the supported tags here (Headerdoc User Guide).

Note The @ symbol is the prefix for each label. Also, you can use the special character switches in the text so that you can change its type and format. For example, text will make the text word bold, and text will also let the text word be of type italic. The interesting thing is that you can also put some text in code form (not a code snippet), and if you write down @ctext, it will cause a different font format to appear when the Help document is displayed on Xcode.

You can also replace the @ symbol with a backslash (\), except as stated above. That way the labels will be shown like this: \brief, \param, \return, and so on. Note that the @ symbol is often used inside the headerdoc. Here we will use @ at all places, because it is common in both systems.

Objective-c Code Documentation

Let's see how the above-mentioned content is used. Open the Viewcontroller.m file and add the following attribute to the private part of the class:

12345

@interface ViewController () @property (nonatomic, strong) NSString *myName; @end

Then add the comment document as follows:

12	/*! @brief This property knows my name. */@property (nonatomic, strong) NSString *myName;

Then, in the Viewdidload method, start entering this property. You'll see the comment that we just wrote in the code fill pop-up box right there!

And not only that. When you hold the option key on the keyboard, clicking the MyName property causes the Help window to pop up:

More, if you open Help Inspector in the utilities panel, you will find the same document there.

Note that in the comments above, the @brief tag can be removed without causing any problems. This means that the following comment is also valid:

12	/*! This property knows my name. */@property (nonatomic, strong) NSString *myName;

Similarly, the following is also the same:

12	/** This property knows my name. */@property (nonatomic, strong) NSString *myName;

And here's the same one:

12	/// This property knows my name. */@property (nonatomic, strong) NSString *myName;

Let's take a look at the first simple example of how to show a document method. At this point you must understand that if your goal is to create an HTML document, then only the public method (in the header file) of the document is visible. Any document you write in the private part of the class is visible in the Xcode help document, but no implementation is exported to the comment document. So, remember this, now let's define a public method in the ViewController.h file:

12345

@interface ViewController : UIViewController -(float)toCelcius:(float)fromFahrenheit; @end

Obviously, this method will convert Fahrenheit to Celsius. Now let's add a comment document:

123456789101112

/*!    @brief It converts temperature degrees from Fahrenheit to Celsius scale.     @discussion This method accepts a float value representing the temperature in Fahrenheit scale and it converts it to the Celsius scale.                  To use it, simply call @c[self toCelsius: 50];     @param  fromFahrenheit The input value representing the degrees in the Fahrenheit scale.     @return float The degrees in the Celsius scale. */-(float)toCelcius:(float)fromFahrenheit;

Note that in the above we use the HTML switch to make all contained text bold and italic, respectively. Also note how we use the @c switch to identify the inline code

To see how this annotated document is presented in Xcode Help, open the Viewcontroller.m file and define the method as follows:

123	-(float)toCelcius:(float)fromFahrenheit{    return(fromFahrenheit - 32) / 1.8;}

Then put the cursor on the method name and view it in quick Help inspector:

You can see that Xcode displays each part of the document in a formatted format. Also in the Help pop-up window (option + click Method name):

If you call this function in the Viewdidload method, you can see the description in the Function AutoFill window:

It's great, isn't it? You can imagine that your code will become much more helpful and self-explanatory when you document it, especially when you work with other team members.

To make this example more interesting, we add another public method just to do the opposite: convert Celsius to Fahrenheit. Open the ViewController.h file, and then add the following method declaration, along with its documentation comments:

1234567891011121314

*!    @brief It converts temperature degrees from Celsius to Fahrenheit scale.     @param  fromCelcius The celsius degrees value.     @returnfloat The degrees inthe Fahrenheit scale.     @code        float f = [self toCelsius:80];    @endcode     @remark This is a super-easy method. */-(float)toFahrenheit:(float)fromCelcius;

In the above paragraph we added two new tags: a pair of @code – @endcode tags and @remark tags. You will immediately see how they are presented.

Let's go to the viewcontroller.m file to implement this method:

123	-(float)toFahrenheit:(float)fromCelcius{    returnfromCelcius * 1.8 + 32;}

Now let's look at the Help popup box as follows:

Very beautiful! Now your own document is no less than the Xcode default document.

Before entering the next section, open the ViewController.h file and add the following attribute declaration (including, of course, comments):

12	/*! An application delegate object. */@property (nonatomic, strong) AppDelegate *appDelegate;

With it, import the Appdelegate class:

1	#import "AppDelegate.h"

The reason for adding the above attribute to the class is that we can later see the property values and how the method we have created is exported using the document tool (Headerdoc).

Let me introduce some new tags that you'll use when you record a file:

• @file: Use this tag to indicate that you are recording a file (header file or not). If you will use Doxygen to output the document, then you'd better write the file name immediately after the tag. It is a top level label.

• @header: Similar to the above, but is used in Headerdoc. When you are not using Doxygen, do not use the label above.

• @author: use it to write down the creator information for this file

• @copyright: Add copyright information

• @version: use it to write down the current version of this file. This is important if the version information is affected during the project life cycle.

Of course you can use more tags, but these are all part of the most common use. I suggest you browse through the Headerdoc document so you can find some additional keywords you want to use.

Now let's look at adding comments to the ViewController.h header file. Locate the beginning of the file, just before the import command. Add the following lines there:

1234567891011

/*! @header  viewcontroller.h     @brief  This is the  header file where my super-code is contained.    this file contains the  most importnant method and properties decalaration. it ' s parted  by two methods in total, which can be used to perform  Temperature conversions.     @author  your_name @copyright   2015 your_name @version      15.12.7 */

You can replace the your_name with your own name or company name. Again, using the brief tag instead of omitting it is a good habit, because it will let the document System (which will be seen later in Headerdoc and Doxygen) show you the short description you added here on the output HTML page. Again, you won't see what the document looks like just now, but we'll show it later when the HTML file is printed.

All of these are great, but the truth is that in most cases, the default annotations that are automatically added by Xcode to the new file you create are very good and sufficient. When you collaborate with others on a team, and each member must describe the details of the files He is responsible for, or when you plan to use Headerdoc to output a complete document for a project, or when you are an independent developer but the project has a large number of files, You may want to create a file description block. Anyway, it's up to you to decide which level your document system needs to refine to.

Once again, I only give the most commonly used labels. Check the documentation yourself for more information about the labels.

• @class: Use it to specify the beginning of a class's comment document block. It is a top level tag, which should be followed by a class name.

• @interface: Ibid.

• @protocol: Same as two, just for protocols

• @superclass: Superclass of the current class

• @classdesign: Use this tag to point out any special design patterns you use for the current class (for example, you can refer to whether this class is a singleton or something similar).

• @coclass: The name of another class that works with the current class.

• @helps: The class name of the current class helper.

• @helper: Help the class name of the current class.

Generating documents using Headerdoc

Now that we've covered the main content of the code comment, let's move on to another section and see how to create an HTML file that contains comments added to the project. In this section, we'll use Headerdoc, a great tool for working with documents written in a file. I recommend you visit this website for more information. We will use Headerdoc to output all the annotation parts of the project to the HTML page. Small projects This may not make much sense, but a corresponding document is necessary for large projects or for you to provide your own SDK for others. The Headerdoc tool is actually a command-line tool. It provides a detailed and different branch to configure the export step, which you can find in the link I provided above. Here, we will use a branch that is useful to specify the branch of the output directory (the directory where the exported document is saved).

Let's see what we can do. First, create a directory for the document that will be generated. For ease of access, I build a directory on the desktop, of course you can choose any directory you like, as long as you update the path you will see later. I created a docdemo directory on my desktop and added a subdirectory here: Headerdoc. The documents generated by each tool are made in their respective folders.

Next, you must open Terminal, You can click LaunchPad > Other group > Terminal, to open or enter under spotlight Terminal to open it.

Now, use terminal to navigate to the directory where your project is located, and use these simple steps to achieve your goal:

1. Write down the CD instruction in terminal and enter the SPACEBAR. Do not press ENTER.

2. In the Finder, navigate to the root directory that contains the project.

3. Drag this directory down to terminal, as shown in.

Then click Enter to ensure that you can use the PWD command (always in terminal) in the correct directory

Here we want to use the Headerdo directive called headerdoc2html, the instruction format is as follows:

headerdoc2html -o OutputDirectory InputDirectory

The OutputDirectory directory is the directory we created earlier, and the input directory is the directory in which the project file exists.

Now, let's actually use it. In the terminal window, write or copy and paste the following instructions:

Headerdoc2html-o

Note: There is a space symbol after-O.

Next, find the directory where the exported documents will be stored in the finder. Follow the steps described above to drag the directory to terminal. After that, enter the input directory address and add a/symbol later. All instructions will look like this:

headerdoc2html -o /Users/gabriel/Desktop/DocDemo/HeaderDoc DocDemoObjC/

OK, done, then go to the desktop Headerdoc inside to look at it, the HTML document has been generated. The following:

iOS Development journal 23-xcode build API documentation (HEADERDOC)