Tech Blogs

perspectives for IT decision makers

Documenting Code in XCode

by (September 18, 2015)

Documenting Code in xcode

When we talk about documenting a code, apparently, it doesn’t mean adding a few comments on the methods of your implementation files. It’s definitely more than that. A good application is not just about writing a clean code, its also about how well its being understood by others. No matter how well-written the code is, if there is no detailed documentation created along with it, chances of trouble arising in future is higher. The worst decision, you might make during the application creation period, would be to skip the comments, even if you are the sole developer or working in a team.

Xcode 5 and Document Support

That said, let us start with the support that Xcode provides to document your code. A small addition was mentioned during the Xcode 5 and iOS 7 announcements that most people might have missed: HeaderDoc and Doxygen. Most of you, as a developer, might have seen that the in-built framework classes and functions are described in the Quick look panels of the XCode. It is possible to have the same effect in your code, also, using the correct format for commenting.

Xcode parses HeaderDoc-style comments behind the scenes to, automatically, present your documentation in quick look panels.

The simplest commenting technique you must have used for sure is:

Error

 

 

But documenting code is more that this simplest form. Code documentation is a structured way to write comments using the special keywords/tags so that the compiler understands it and help you and others in future implementation.

Using these, your documentation can be displayed in three different places:
1. Quick Help Inspector – In the Utilities panel.
2. Help Popup – That is displayed when you press the Option key and click on the name of method, class or property.
3. In the code-completion popup.

There are three possible ways to mark a documentation area when writing code in Objective-C.

Comments

 

It is interesting to note that it is incredibly simple and easy to add documentation to a property. For e.g. Add the option on a property, as below, and when option is -clicked, this popover will be shown:

Code Window

 

 

 

 

 

 

In case of commenting on functions, you can use header tags which will provide more details of the methods. Let us see how that is achieved now.

HeaderDoc Tags

There are 2 types of tags:

  • Top-Level Tags: These are the tags that declare the type of item/parameter you are commenting on (Headers, classes, methods, etc).
  • Second-Level Tags: These tags help to give more detail about the specific item/parameter you are commenting on.

Let us concentrate on the second level tags, first. Some of the tags are as follows:

  • @brief
  • @discussion
  • @param
  • @return
  • @see
  • @code — @encode
  • @warning
  • @remark

You can find a full list of all supported tags in HeaderDoc UserGuide.

Code Documenting in Objective C

Let us learn how these can be, actually, used in the code. Documenting a method can be done as follows:

For example:  Let us add a @description tag, two @param tags and a @return tag to the function as follows:

Coding in Objective C

 

On Option + Click, you can see the following window. You can, also, check the Quick Help in the Utilities panel. You will find the same description there, too.

Data Fetch

The code completion popup, which is displayed, when you write the function name, will now include the description of the function, along with the method quick view.

Fetch data

Other options, you can include in the commenting, are @codes, @warnings, etc. Please refer the below sample:

Commeting Codes

And the result is as follows:

Result of commenting

 

 

 

 

 

 

 

To learn more, on Documenting Classes, Structs, Enums and Documenting in Swiftdownload the full article here.

By,

Sudeep KS

iOS and Swift Developer, RapidValue Solutions

Sorry no comment yet.

LEAVE A COMMENT

24/7 Toll Free(877)-643-1850(US)

Would you like to know more about us?

  • This field is for validation purposes and should be left unchanged.
Scroll Top