转载:Xcode4自动生成注释和开发文档
Doxygen
是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的
批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个
纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。 对于未归档的源
文件,也可以通过配置Doxygen来提取代码结构。或者借助自动生成的包含依赖图(includedependency
graphs)、继承图(inheritance
diagram)以及协作图(collaborationdiagram)来可视化文档之间的关系。Doxygen生成的帮助文档的格式可以是CHM、
RTF、PostScript、PDF、HTML和Unixman page等。
xcode3里面可以根据系统集成的HeaderDoc工具来达到目的, 还很方便, 具体见
http://blog.csdn.net/arthurchenjs/article/details/6945286#reply
doxygen当然也可以用于xcode3, 利用xcode3 add user scripts配置一个doxygen.rb脚本即可, 见:
原文:
译文:
Xcode4方法:
1.生成注释
要自动加上注释和生成文档, 注释也是有一些格式的:
变量结构体的注释方式为
-
-
NSString
*modelName;
也可以这样:
- int
i;
注意 前面有空格, 最好加上
方法的注释为:
-
- -(void)searchButtonAction:(id)sender;
这些格式如果一个一个手动敲上去那也太麻烦了, 得不偿失, 这里有写好的脚本可以直接用, 设置好了一个快捷键就行!
Xcode4和3变化很大, HeaderDoc好像没有了, 至少我目前没找到, User Scripts也不支持了
不过还是有2种方法可用, 第一种, 下载下面这个老外自己写的一个workflow, 配置到xcode,
设置快捷键既可以用
first download the service.
Next, unpack the file and copy it to your ~/Library/Services directory. The name of the service is “Document Code” though you can rename it to anything you’d like. This is the name that will appear in the Services menu.
Once you have the service installed, you need to open System Preferences. Select the “Keyboard” preference pane, and select the “Applications Shortcuts” configuration in the “Keyboard Shortcuts” tab.
Click the + button to add a shortcut for our new service.
然后在xcode里面选中需要注释的代码, 直接利用你刚刚设置的快捷键就会自动加上注释!
第二种方法是利用一个mac工具原封不动的把在xcode3里面运行得好好的rb脚本配置到系统的服务里面, 设置一个快捷键也可以, 上面那位仁兄写的那个workflow效率一般, 我试过了, 用起来很卡, 还是原来的好, 建议用这个方法! (http://www.brokenrul.es/blog/?p=761#.TtXrJL92Re4)
Since I couldn’t find a good solution for creating a keyboard
shortcut to create a doxygen snippet based on your selection in
XCode4 I have to write a short and untypical technical blog post
about how to get that.
We’re trying to document our code as
good as possible. While well written code is self-explainatory,
interfaces and functions in header files simply have to be
documented correctly. To do so, we useDoxygen, here in the
Broken Rules engine room. We’ve had a pretty good XCode integration
for generating Doxygen snippets on the press of a button but XCode4
broke the scripting support. In order to get our comfortable
scripts back I had to look at a nearly forgotten part of the OSX
operating system: Services.
You need the following two things in order to install the Ruby-based doxygen generator script that I’m using:
- Waffle Software’s ThisServices, a tool to quickly hook up your own scripted services in OSX’s “Services” menu.
-
Doxygen.rb based on
Fred McCann’s doxygen script.
Then simply execute the following two steps in order to install the script and make it start on the press of a key.
First, start ThisService and create a new “Filter”-type service based on the above Ruby script. Simply select Ruby file and give it a name. Then select “Filter” as the type of service and leave the rest of the controls untouched. Your settings should look like this:
Press “Create Service” to create the service. Once
that is done you can proceed to step two.
Next, open “System Preferences” and go to “Keyboard” > “Keyboard Shortcuts”. Select “Services” in the left pane. Browse for the name you gave your new service. It’s hidden somewhere in the huge list of services. Once you’ve found it you have to assign a keyboard shortcut and tick its checkbox, otherwise it will not show up in your “Services” menu:
Once you’ve set the shortcut, you’re done. Simply select any text in XCode and press your keyboard shortcut. The script will try its best at understanding your code but you might have to extend it in order to suite your coding habits. Have fun!
2.生成文档
首先下载Doxygen, 下载地址:
可以svn下载源码, 也可以直接当前最新版 Doxygen-1.7.5.1.dmg
配置选项含义详解
用文本方式打开Doxyfile文件,可以看到Doxygen的参数配置项特别多,各个参数的含义其实也并不难掌握,在Doxygen的帮助手册中有详细的介绍,下面我介绍一些常用的参数含义,其余的参数大多可以设置为默认值。
DOXYFILE_ENCODING |
Doxygen文件的编码方式,默认为UTF-8,若希望支持中文,最好设置为 GB2312 |
PROJECT_NAME |
Project 的名字,以一个单词为主,多个单词请使用双引号括住。 |
PROJECT_VERSION |
Project的版本号码。 |
OUTPUT_DIRECTORY |
输出路径。产生的文件会放在这个路径之下。如果没有填这个路径,将会以目前所在路径作为输出路径。 |
OUTPUT_LANGUAGE |
输出语言, |
EXTRACT_ALL |
为NO,只解释有doxygen格式注释的代码;为YES,解析所有代码,即使没有注释 |
EXTRACT_PRIVATE |
是否解析类的私有成员 |
EXTRACT_STATIC |
是否解析静态项 |
EXTRACT_LOCAL_CLASSES |
是否解析源文件(cpp文件)中定义的类 |
INPUT |
指定加载或找寻要处理的程序代码文件路径。这边是一个表列式的型态。并且可指定档案及路径。 |
FILE_PATTERNS |
如果您的INPUT Tag
中指定了目录。您可以透过这个Tag来要求Doxygen在处理时,只针对特定的档案进行动作。例如:您希望对目录下的扩展名为.c,
.cpp及.h的档案作处理。您可设定FILE_PATTERNS = *.c, *.cpp,
*.h。 |
RECURSIVE |
这是一个布尔值的Tag,只接受YES或NO。当设定为YES时,INPUT所指定目录的所有子目录都会被处理. |
EXCLUDE |
如果您有某几个特定档案或是目录,不希望经过Doxygen处理。您可在这个Tag中指定。 |
EXCLUDE_PATTERNS |
类似于FILE_PATTERNS的用法,只是这个Tag是供EXCLUDE所使用。 |
SOURCE_BROWSER |
如果设定为YES,则Doxygen会产生出源文件的列表,以供查阅。 |
INLINE_SOURCES |
如果设定为YES ,则函数和类的实现代码被包含在文档中 |
ALPHABETICAL_INDEX |
如果设定为YES,则一个依照字母排序的列表会加入在产生的文件中。(有很多类、结构等项时建议设为YES) |
GENERATE_HTML |
若设定为YES ,就会产生HTML版本的说明文件。HTML文件是Doxygen预设产生的格式之一。 |
HTML_OUTPUT |
HTML文件的输出目录。这是一个相对路径,所以实际的路径为OUTPUT_DIRECTORY加上HTML_OUTPUT。这个设定预设为html。 |
GENERATE_HTMLHELP |
是否生成压缩HTML格式文档(.chm) |
HTML_FILE_EXTENSION |
HTML文件的扩展名。预设为.html。 |
HTML_HEADER |
要使用在每一页HTML文件中的Header。如果没有指定,Doxygen会使用自己预设的Header。 |
HTML_FOOTER |
要使用在每一页HTML文件中的Footer。如果没有指定,Doxygen会使用自己预设的Footer。 |
HTML_STYLESHEET |
您可给定一个CSS 的设定,让HTML的输出结果更完美。 |
GENERATE_HTMLHELP |
如设定为YES,Doxygen会产生一个索引文件。这个索引文件在您需要制作windows 上的HTML格式的HELP档案时会用的上。 |
GENERATE_TREEVIEW |
若设定为YES,Doxygen会帮您产生一个树状结构,在画面左侧。这个树状结构是以JavaScript所写成。所以需要新版的Browser才能正确显示。 |
TREEVIEW_WIDTH |
用来设定树状结构在画面上的宽度。 |
GENERATE_LATEX |
设定为YES 时,会产生LaTeX 的文件。不过您的系统必需要有安装LaTeX
的相关工具。 |
LATEX_OUTPUT |
LaTeX文件的输出目录,与HTML_OUTPUT用法相同,一样是指在OUTPUT_DIRECTORY之下的路径。预设为latex。 |
LATEX_CMD_NAME |
LaTeX程序的命令名称及档案所在。预设为latex。 |
GENERATE_RTF |
若设定为YES ,则会产生RTF 格式的说明档。 |
RTF_OUTPUT |
与HTML_OUTPUT 用法相同,用来指定RTF 输出档案路径。预设为rtf。 |
GENERATE_MAN |
若设定为YES ,则会产生Unix Man Page 格式的说明文件。 |
MAN_OUTPUT |
与HTML_OUTPUT 用法相同,用来指定Man Page的输出目录。预设为man。 |
GENERATE_XML |
若设定为YES ,则会产生XML 格式的说明文件。 |
ENABLE_PREPROCESSING |
若设定为YES ,则Doxygen 会激活C
的前置处理器来处理原始档。 |
PREDEFINED |
可以让您自行定义一些宏。类似于gcc 中的-D选项。 |
CLASS_DIAGRAMS |
这个标记用来生成类继承层次结构图。要想生成更好的视图,可以从 Graphviz 下载站点 下载 dot 工具。Doxyfile 中的以下标记用来生成图表: |
HAVE_DOT |
如果这个标记设置为 Yes,doxygen 就使用 dot 工具生成更强大的图形,比如帮助理解类成员及其数据结构的协作图。注意,如果这个标记设置为 Yes, 标记就无效了 |
CLASS_GRAPH |
如果 标记和这个标记同时设置为 Yes,就使用 dot 生成继承层次结构图 |
GRAPHICAL_HIERARCHY |
设置为YES时,将会绘制一个图形表示的类图结构 |
Adding a Doxyfile to a Project
I’ve spent a lot of time telling you how to comment your code, but I have yet to show you how to generate the documentation. We’re going to add a Doxyfile to your project. A Doxyfile is a configuration file that instructs Doxygen how to extract comments from your code. Doxygen is packaged with a decent GUI application for OS X. To get it, go to theDoxygen downloads page and download the package for your version of OS X.
After you’ve downloaded the application, install it in your /Applications folder. Now that we have Doxygen installed, start the application and we’ll make our first Doxyfile.
Doxygen opens up in wizard mode. The first two fields we need to set are the working directory and the destination directory. Set the working directory to your project directory. Set the destination directory to where ever you’d like your documentation generated. You can make this a relative path. You may also want to modify the source code directory if you’ve structured your project directory with subfolders.
Next, we’re going to click on the Expert tab and check the JAVADOC_AUTOBRIEF option in the Project section. This will allow us to use javadoc style brief descriptions in our comments.
Now select the Build section and check the EXTRACT_ALL option. You don’t need this set, but having this checked will extract as much information as possible from your code. You should start with this to see what Doxygen can do and revisit these settings as you get a feel for Doxygen.
Navigate to the HTML section and select the GENERATE_DOCSET option. This will allow us to add our documentation to Xcode. I’ll cover how to do that in a separate section. You should also fill in the DOCSET_FEEDNAME as this will be the name of your docset, and the DOCSET_BUNDLE_ID field with the reverse-DNS name for your company and product.
In the LaTeX section, uncheck the GENERATE_LATEX option. You can leave this checked if you want documentation generated in this format.
Save your configuration file with the File > Save command. I recommend saving this in the root of your project directory. Now when you need to run Doxygen, you have all your settings ready to go. While we’re at it, select the “Run” tab and run Doxygen. You should get some logs that look like this:
Now you’ve generated documentation from your headers!
Adding your Documentation to Xcode
Having documentation is great in and of itself, but how insanely great would it be if we could browse our docs directly in Xcode? There is where the GENERATE_DOCSET option comes in.Docsets are bundles of documentation that Xcode can load into its documentation browser.
Where is the docset we configured Doxygen to build? Doxygen doesn’t make the docset for us automatically. Instead it creates a Makefile we can use to create and install a docset. Open the terminal application and change the directory to where your documentation was created. In that directory, you should have an html directory for the html docs you generated. Enter that directory and you should have a Makefile. Run “make install” in this directory, and make will package your html docs as a docset and install it in ~/Library/Developer/Shared/Documentation/DocSets. You need to restart Xcode for it to notice the new docset. Once you’ve done this, you can browse your documentation in Xcode.
Now we can use Xcode to navigate our own documentation!
Generating Documentation as Part of Your Xcode Build
At this point, we know how to comment our code, we have a helper to reduce the work involved, and we know how to generate our documentation and add it to Xcode. This is great, but we still need to remember to regenerate our documentation every now and again. We can take this one step further and automate the process of generating code as part of our project build.
To do this we need to add a script to our build. First you need to download a shell script that will call the Doxygen executable in your /Applications directory:
Open the script in a text editor and copy the contents. The open your project in Xcode and right click on the target, selecting Add > New Build Phase > New Run Script Build Phase from the contextual menu.
Adding the Run Script Build Phase will add the new phase and open its info window. Paste the downloaded script into the script section of this window:
There’s one more step. The script needs to know what domain name to use for your documentation bundle. The general practice is to use the reverse domain name of your organization. Since this blog is at duckrowing.com, I’m going to set my domain name to “com.duckrowing”. To do this, right click on your target and select Get Info from the contextual menu. This will open the Target Info window. Select the Build tab and using the button in the lower left of the window, add a new User-Defined Setting.
The new setting will be called “COMPANY_RDOMAIN_PREFIX”. Set your value and close the window.
That’s the last step. From this point forward, building your project will generate your documentation, create a docset, and tell Xcode to load the changes. There’s no longer a need to run Doxygen manually nor do you need to restart Xcode to see changes in your documentation. So long as you keep adding documentation as you go along, your project documentation will always be up to date!
If you need to remove any of the docsets you’ve added to Xcode, open your ~/Library/Developer/Shared/Documentation/DocSets and throw away any docsets you no longer want.
Creating documentation for our Objective-C projects doesn’t have to be a chore. With a few steps up front we can adapt Xcode to both help us write our comments and generate our documentation as a normal part of our workflow. This information should be enough to get you started on the way to well documented projects. Enjoy!
参考:
http://www.duckrowing.com/2011/05/14/using-the-doxygen-helper-in-xcode-4/
http://www.duckrowing.com/2010/03/18/documenting-objective-c-with-doxygen-part-i/