Documenting Objective-C with Doxygen Part I
来源:互联网 发布:网络借贷平台排行 编辑:程序博客网 时间:2024/04/30 05:30
When working on a projects, whether they consist of a single file or hundreds of classes, documentation is a requirement. Nothing, not even a robust test harness is as critical to the longevity of code than good documentation. Documentation is what allows us to collaborate, use libraries written by people we’ve never met, and remember exactly what we were thinking when we revisit our own code. If you have any doubt that documentation is the most important component of a project besides the actual source code, ask yourself how far you would get with Cocoa without the developer documentation.
Java is far from a perfect language or a perfect platform. One thing the guys at Sun got right from the beginning was Javadoc. Java has a standard format for commenting your code and a single common tool for extracting these comments into well formatted documentation. Javadoc generated documentation won’t win any contests for web design, but one of the reasons that there are so many widely used Java libraries is because you never see a library lacking this minimal level of documentation.
Java is not alone. Ruby has RDoc. PHP has phpDocumenter and others. While not every language has a single official documentation system like Java, there’s usually one or two de-facto standards used by the community. For a list of documentation tools, look here.
When I was first starting out with Objective-C, I took a look around to see what Objective-C coders use for their documentation. I did not find a clear answer. Also, I couldn’t find a lot of great examples of fully documented code. I hope this blog post helps fill in the blanks for anyone who finds themselves in a similar situation.
In this post, I’ll show you how to comment your header files using Doxygen. Why am I using Doxygen? As near as I can tell, Doxygen seems to be the best solution available for documenting Objective-C code. It appears that there used to be a tool called AutoDoc, but I can’t find much information on it. There’s also Apple’s own HeaderDoc. My assumption was that Apple’s tool must be the best tool for the job. After playing with it, I’m not so sure. Even though Apple provides documentation for using the tool and even provides support for generating HeaderDoc comments in Xcode, I found it to be a bit lacking. One problem I had was that I couldn’t find any guidance for how to document Objective-C 2.0 properties. I have these all over my code, so this was troubling. That left Doxygen, which does a decent job of creating documentation, supports Javadoc style documentation (which means most of us don’t have to learn a new way of doing things), and can actually package the generated documentation for use in Xcode.
One thing to mention before we get to some examples is that Doxygen is a tool designed parse your header files, not implementation files. I don’t mean to imply that you should not comment your implementation files. The point of a tool like Doxygen is to document the external interfaces to your code. When we document code, and more importantly when we design software, we should think in terms of interfaces and how code call those interfaces. Not only will this lead to great documentation but you might find that this approach leads to better software.
Documenting C Constructs
Let’s start with documenting common C language constructs before we get to Objective-C. Here’s some examples of variable and constant declarations:
These comments should look somewhat familiar to anyone who’s written Javadoc comments. We’ll be using Doxygen’s JAVADOC_AUTOBRIEF setting, which mimics some of Javadoc’s behavior. When Doxygen parses these comments, the first sentence (demarcated by the first period) will become the brief description. The entire comment makes up the full description. The brief description is a succinct note on what the element we’re documenting represents. The full description can be used to provide an in-depth explanation. Note that my comments are not entirely the same as used in javadoc. Doxygen supports putting an asterisk on every line like javadoc comments, but since Xcode automatically add an asterisk on every line like other IDEs, I’m not using them.
In the case where we define multiple variables of the same type at once, we again deviate a bit from javadoc style:
Again, this is very javadoc like if not exactly like javadoc comments. You have the option of adding comments above the declarations or on the right hand side as we see here. Generally if you need long descriptions, do not use this inline format.
Let’s look at how we document enumerations:
At this point, the code is commented, which is great. The next time you look at this, you’ll know what each type of user is good for. So far though, we haven’t seen any really big wins from documenting in this style. The payoff will come when we get to functions and classes. But just to keep you interested, take a look at the documentation that Doxygen generates just from what little work we’ve done so far: Generated Documentation
I admit that Doxygen generated html, much like the output of the Javadoc tool, will not win any design awards, but this is great stuff to have. Imagine you’re revisiting your code a year from now or you’re bringing someone new on to your team; having these sorts of docs can save a lot of time.
Now let’s take a look at C structures:
So far, it’s virtually the same as what we’ve seen before. We use a comment before the struct Song to describe the structure, and either inline or full comments to describe each member. In general you’ll probably not mix these styles as I have here. This is just to point out that you can chose either one. We can also comment our typedefs, which Doxygen has no problems parsing.
Unions as you might expect are handled the same way as structures:
Take a look how Doxygen presents structs and unions: Generated Documentation
The last basic C construct I’ll cover is macros. We use the #define directive to make macros in C, and they may or may not take parameters:
The first two examples are straight forward enough. We just add a simple comment before each macro. The third example is where things get interesting; we start using some tags in our comments. The @param tag is used to describe a parameter to a function or method. The @returns tag is used to define what a function or method returns. You’ll notice that we name which parameter we’re describing in the @param tag.
Tagged comments are more useful than just adding notes in an unstructured way. We now have a clear, consistent way of documenting parameters and return types. Take a look at how Doxygen documents macros: Generated Documentation
All this extra work starts paying off once we start documenting parameters and return values. Now that we’ve seen how to do this, let’s look at some function prototypes:
In the case of functions, we’re reusing the same @param and @returns tags. Notice that we do not need the @returns tag for the second function as it does not return anything. See how Doxygen documents functions: Generated Documentation
Documenting Objective-C Constructs
While it’s great to have a C refresher, you’re likely reading this because you’re interested in documenting Objective-C classes and methods. At this point you’ve seen enough to get started, but let’s be thorough and show some examples for common Objective-C constructs.
To start off with, let’s take a look at how we would comment and Objective-C class:
Commenting an Objective-C class is what you would expect. We have a comment for the @interface declaration and comments for each of the instance variables. Let’s take a look at how we document Objective-C 2.0 properties:
We’ve marked up properties in the same way we’ve marked up other declarations. The thing to note is that we have not documented every property. The properties modelName and modelNumber do not have any comments. We don’t need to comment these properties as we’ve already documented their instance variables. Doxygen is smart enough to realize this. If we documented both the instance variables and the property declarations, we’d end up with double documentation in our generated html. We explicitly added comments for the price and usDollars properties. We removed the comment from the price instance variable and added it to the property instead. You have the option of documenting either the instance variable or the corresponding property. Either way is fine though you should decide on what way you prefer and stick with it. The final property, usDollars, must be commented at the property level as it does not correspond to an instance variable.
Let’s add a method to the Automobile class and comment it:
Again we rely on the @param and @returns tags to comment this method. Take a look at the generated documentation for the Automobile class: Generated Documentation
If we need to document an Objective-C category, it’s essentially the same as documenting a class. Here’s an example:
Generated Documentation
For the sake of completeness, here’s an Objective-C protocol:
Generated Documentation
It’s worth noting that I had some problems with Doxygen when using @class declarations with protocols. Even with the few issues Doxygen has, it’s still a great tool for documenting Objective-C code.
Additional Documentation Tags
There are a number of additional tags we can use in the bodies of our comments to give the reader more information. Here’s a list of popular javadoc style tags that Doxygen supports:
@author name | URL | email address
Use this tag to claim ownership of a portion of the code base. This supports adding a name, URL, or email address.
@deprecated text
Use this to indicate that the commented piece of code will be removed at some point in the future.
@exception type text
Use this to indicate that the commented piece of code may thrown an exception.
@see text | URL | classname | classname#methodname
Use this to tag to refer the reader to some other source of related information.
@since text
Add a note describing at what point this part of the interface became available.
Let’s use these in a fairly contrived example:
Generated Documentation
These are not the only tags you can use with Doxygen, though these are ones you might commonly find a use for. For complete documentation on allowed tags and to see how to add lists, formulas, and other markup to comments, take a look at the Doxygen user’s manual.
That covers how to comment your code for use with Doxygen. In part II I’ll cover how to make writing all these comments a bit easier, how to run the Doxygen generator, and how to integrate generated documentation into your build process and into Xcode’s documentation system.
- Documenting Objective-C with Doxygen Part I
- Documenting Objective-C with Doxygen Part II
- Monkey-Patching iOS with Objective-C Categories Part III: Swizzling
- Playing with ptrace, Part I
- Playing with ptrace, Part I
- Playing with ptrace, Part I
- Playing with ptrace, Part I
- Playing with ptrace, Part I
- Objective-C Programming: The Big Nerd Ranch Guide (2nd Edition) 阅读笔记(Part I & II)
- objective-c I/O
- Programming with objective-c
- PostgreSQL cluster: partitioning with plproxy (part I)
- Getting Start with GWT(Part I)
- Getting started with windbg - part I
- OpenGL programming with GLSL: Part I
- Thinking in C++, Part I
- Programming with Objective-C --- 关于Objective-C
- 用Doxygen为objective-c代码生成文档
- 步入Matrix函数
- linux按键驱动示例
- Query 接口初步
- 我该怎么办
- Linux Kernel: 简介HZ, tick and jiffie
- Documenting Objective-C with Doxygen Part I
- 25个最佳最闪亮的Eclipse开发项目
- 由“让座”想到的
- WebKit中的设计模式(二),单例模式
- JavaScript中$以及金额大小写
- atmega8 例程:按键输入检测
- adpcm 转换wave
- 实训心得
- 用ExpandableListView实现类似QQ好友列表