使用Doxgen创建Xcode文档集
2011-03-03 17:58
197 查看
文档集为Xcode开发者提供了一个查找各种文档的便捷方式,包括:API、指南、教程、Q/A、示例代码及其他。
许多开发者都用过苹果文档集,如下图所示:
![](http://hi.csdn.net/attachment/201103/3/0_1299145036sKJZ.gif)
Figure 1:
Xcode中的苹果文档集
在Xcode3.0中,通过Xcode的Documentation窗口,可以集成苹果文档集之外的文档集。这样,可以想苹果文档集一样,使用Xcode的Document
Browser浏览这些文档。此外,还可象API文档一样和Xcode的搜索助手集成,如下图所示,当代码编辑器中选择代码时,可以提示API文档内容和编译设置。点击相应的符号链接,可以跳转到对应的文档。
![](http://hi.csdn.net/attachment/201103/3/0_1299145231tXtx.gif)
Figure 2:
Xcode
中的搜索助手
Note:
使用菜单
Help > Show/Hide Research Assistant
开启搜索助手
.
本文显示了如何生产文档,把文档封装到文档集并放到Xcode能认识的路径下。另一种方法是把文档集发布为feed(基于RSS订阅机制)。RSS
feed常用于各种规模的开发团队,用RSS feed方式在Xcode安装文档集,你能轻易地自动接收文档集的更新。
正如文档集指南(本文后附有链接)所述,文档集有着定义良好的结构。为避免完全使用手工***的繁琐,开源的Doxygen能从你的源代码中自动产生文档——包括生成html、打包和部署,从而使你把精力放到文档的内容上。
Doxygen
Doxygen从源代码生成文档。它能生成多种格式的在线或离线文档。它支持c/c++,Objective
C,Java,Python等多种编程语言。在这里,我们将用它从Xcode Objective C工程中生成Html文档集。下面列出了该项目的一个头文件,当然,源代码中的注释越多,Doxygen生成的文档内容就越多。
Listing 1:
DoxygenExample.h
//
//
DoxygenExample.h
//
DoxygenExample
//
//
Created on 1/31/08.
//
Copyright 2008 __MyCompanyName__. All rights reserved. //
#import <Cocoa/Cocoa.h>
/**
Sample interface */
@interface DoxygenExample : NSObject {
}
/**
This method does nothing. */
- (void)doNothing;
@end
使用
Doxygen GUI
首先,从Doxygen网站上下载Doxygen(见文后的链接)。Doxygen主页上有Doxygen磁盘镜像文件(.img)的下载链接,同时也提供最新的源代码。Doxygen
GUI提供了Mac下的用户界面,比起命令行方式要更易于使用,其界面如下图:
![](http://hi.csdn.net/attachment/201103/3/0_1299145342fMd8.gif)
Figure 3:
Doxygen GUI
该界面列出了生成文档的必须步骤。第1步是配置使用Doxygen的模式
:Wizard向、Expert、Load。Wizard(向导模式)对于不太熟练的人更容易些,但通常使用Expert(专家模式)更加灵活。Load(导入模式)则允许使用已有的配置文件进行工作。当你改变设置之后,点击Save按钮并选择文件地址即可按指定文件名保存配置文件。接下来,指定源代码目录。然后,点Start按钮开始生成文档。
现在,可以来看看如何创建文档集了。
Generating a Doc Set
用Doxygen GUI创建文档集很简单。在下图中,显示的是Expert模式的Html设置标签。大部分设置保持默认就可以了,但Output(输出)必须指定。注意勾选Generate_html选项。确认勾选了Generate_docset选项。Docset_feedname的值会在Xcode的documentation窗口显示,所以哪怕你并不是想要创建一个RSS
feed文档集,也要在这里填上一个有意义的名字。使用公司名+产品名的反DNS方式命名Docset_bundle_id。
![](http://hi.csdn.net/attachment/201103/3/0_1299145610q8uU.gif)
Figure 4:
配置
Doxygen
接着,点图3中的Start按钮,Doxygen将根据一个Makefile文件生成HTML文档。用这个Makefile文件运行“make
install”命令,Doxygen会将HTML文档打包、安装为可以在Xcode documentation窗口中打开的文档集。
注:Xcode在目录
/Users/$USER/Library/Developer/Shared/Documentation/DocSets/
下查找文档集,其他的文档集查找目录列在<文档集指南>中了。
使用Xcode生成文档集
另一种创建文档集的方法是在Xcode项目中创建。为此,需要在Xcode项目中增加一个Build
Phase Script。Xcode把它叫做“Run Script Build Phase”。图5显示了添加“Build Phase Script”菜单。图6中,在target下高亮显示的就是一个Run
Script Phase。
![](http://hi.csdn.net/attachment/201103/3/0_1299145670Xsh3.gif)
Figure 5:
在
Xcode
中添加一个
Run Script Build Phase
![](http://hi.csdn.net/attachment/201103/3/0_1299145732jkMK.gif)
Figure 6:
Run Script Build Phase
添加完成后,双击该“Run Script Build Phase”,显示脚本编辑窗口。复制列表2中的脚本到脚本窗口中,结果如图7所示。
Listing 2:
Doc Set Build Script
#
Build the doxygen documentation for the project and load the docset into
Xcode.
#
Build the doxygen
documentation for the project and load the docset into Xcode.
#
Use the following to
adjust the value of the $DOXYGEN_PATH User-Defined Setting:
#
Binary
install location: /Applications/Doxygen.app/Contents/Resources/doxygen
#
Source build
install location: /usr/local/bin/doxygen
#
If the config file
doesn't exist, run 'doxygen -g $SOURCE_ROOT/doxygen.config' to
#
a get default file.
if ! [ -f $SOURCE_ROOT/doxygen.config ]
then
echo doxygen config file
does not exist
$DOXYGEN_PATH -g
$SOURCE_ROOT/doxygen.config
fi
#
Append the proper
input/output directories and docset info to the config file.
#
This works even though
values are assigned higher up in the file. Easier than sed.
cp $SOURCE_ROOT/doxygen.config $TEMP_DIR/doxygen.config
echo "INPUT = $SOURCE_ROOT" >> $TEMP_DIR/doxygen.config
echo "OUTPUT_DIRECTORY = $SOURCE_ROOT/DoxygenDocs.docset"
>> $TEMP_DIR/doxygen.config
echo "GENERATE_DOCSET
= YES" >>
$TEMP_DIR/doxygen.config
echo "DOCSET_BUNDLE_ID
=
com.mycompany.DoxygenExample" >> $TEMP_DIR/doxygen.config
#
Run doxygen on the
updated config file.
#
Note: doxygen creates a
Makefile that does most of the heavy lifting.
$DOXYGEN_PATH $TEMP_DIR/doxygen.config
#
make will invoke
docsetutil. Take a look at the Makefile to see how this is done.
make -C $SOURCE_ROOT/DoxygenDocs.docset/html install
#
Construct a temporary
applescript file to tell Xcode to load a docset.
rm -f $TEMP_DIR/loadDocSet.scpt
echo "tell application /"Xcode/"" >>
$TEMP_DIR/loadDocSet.scpt
echo "load documentation set with path
/"/Users/$USER/Library/Developer/Shared/Documentation/DocSets//""
>>
$TEMP_DIR/loadDocSet.scpt
echo "end tell" >> $TEMP_DIR/loadDocSet.scpt
#
Run the load-docset
applescript command.
osascript $TEMP_DIR/loadDocSet.scpt
exit 0
![](http://hi.csdn.net/attachment/201103/3/0_1299145796gGtd.gif)
![](file:///Users/kmyhy/Library/Caches/TemporaryItems/msoclip/0/clip_image002.png)
Figure 7:
输入或拷贝脚本到脚本窗口
你也许注意到了,脚本中使用了一个指向Doxygen执行文件目录的变量。这是必须的,因为Doxygen的二进制安装和源代码安装的
安装路径是不同的,正如脚本开头所述。图8显示了Target在使用 Get Info 命令后显示的信息.
![](http://hi.csdn.net/attachment/201103/3/0_12991458834SxU.gif)
Figure 8:
Target
的
Info
窗口
在build面板,“User-Defined Settings”菜单可以设置环境变量,从而可以用于编译过程中。图9显示如何进行设置。
![](http://hi.csdn.net/attachment/201103/3/0_1299145965b3bp.gif)
![](file:///Users/kmyhy/Library/Caches/TemporaryItems/msoclip/0/clip_image002.png)
Figure 9:
添加一个
User-Defined
Setting
图10, 把 Doxygen 二进制文件所在目录添加到环境变量。
![](http://hi.csdn.net/attachment/201103/3/0_1299146031selV.gif)
Figure 10:
设置
Doxygen
目录
编译Xcode项目。在Run Script Phase执行后,会生成文档集。编译结果如图11。
![](http://hi.csdn.net/attachment/201103/3/0_12991460862Z6r.gif)
Figure 11:
编译结果窗口
Doxygen的可配置性很好,但要创建Xcode可以打开和搜索的文档集并不需要进行太多的设置。列表2的脚本在别的Xcode项目中仍然可以使用,但需注意以下几点:
使用Doxygen创建文档集的第一步是需要创建一个Doxygen配置文件——它告诉Doxygen关于输出路径。在脚本里我们用doxygen
–g命令生成了一个默认的配置文件 。
默认配置文件有的地方需要修改。在脚本里我们简单地在配置文件后面添加新的设置。这样虽然也行,但可能不符合美学观点。
也许用sed编辑是一种更优雅的做法,它需要写更多的代码,却没有人去看配置文件。
该脚本生成了一个AS脚本,让Xcode打开新的文档集,从而你可以查找类、接口或者方法名,如图12所示。
![](http://hi.csdn.net/attachment/201103/3/0_1299146136NH7h.gif)
Figure 12:
新的文档集
注:如果文档集没有相应的feed URL,会在文档集名称旁有一个Subscribe按钮。
Doxygen是高度可配置的,并可生成多种格式的文档。这仅仅是生成HTML文档集的例子,如果你需要生成其他格式的配置和Makefiles文件,或者你想体验一下Doxgen最新的源代码版本,请浏览Doxygen网站,那里提供了Doxygen的下载、编译及安装指南。
其他信息
本文中的技术需要用到Doxygen。
ADC Reference Library
文档中列出的下列资源将是有用的
:
Documentation Set Guide
Xcode User Guide
以及 Doxygen 相关资源:
Doxygen home page
SourceForge project page
许多开发者都用过苹果文档集,如下图所示:
![](http://hi.csdn.net/attachment/201103/3/0_1299145036sKJZ.gif)
Figure 1:
Xcode中的苹果文档集
在Xcode3.0中,通过Xcode的Documentation窗口,可以集成苹果文档集之外的文档集。这样,可以想苹果文档集一样,使用Xcode的Document
Browser浏览这些文档。此外,还可象API文档一样和Xcode的搜索助手集成,如下图所示,当代码编辑器中选择代码时,可以提示API文档内容和编译设置。点击相应的符号链接,可以跳转到对应的文档。
![](http://hi.csdn.net/attachment/201103/3/0_1299145231tXtx.gif)
Figure 2:
Xcode
中的搜索助手
Note:
使用菜单
Help > Show/Hide Research Assistant
开启搜索助手
.
本文显示了如何生产文档,把文档封装到文档集并放到Xcode能认识的路径下。另一种方法是把文档集发布为feed(基于RSS订阅机制)。RSS
feed常用于各种规模的开发团队,用RSS feed方式在Xcode安装文档集,你能轻易地自动接收文档集的更新。
正如文档集指南(本文后附有链接)所述,文档集有着定义良好的结构。为避免完全使用手工***的繁琐,开源的Doxygen能从你的源代码中自动产生文档——包括生成html、打包和部署,从而使你把精力放到文档的内容上。
Doxygen
Doxygen从源代码生成文档。它能生成多种格式的在线或离线文档。它支持c/c++,Objective
C,Java,Python等多种编程语言。在这里,我们将用它从Xcode Objective C工程中生成Html文档集。下面列出了该项目的一个头文件,当然,源代码中的注释越多,Doxygen生成的文档内容就越多。
Listing 1:
DoxygenExample.h
//
//
DoxygenExample.h
//
DoxygenExample
//
//
Created on 1/31/08.
//
Copyright 2008 __MyCompanyName__. All rights reserved. //
#import <Cocoa/Cocoa.h>
/**
Sample interface */
@interface DoxygenExample : NSObject {
}
/**
This method does nothing. */
- (void)doNothing;
@end
使用
Doxygen GUI
首先,从Doxygen网站上下载Doxygen(见文后的链接)。Doxygen主页上有Doxygen磁盘镜像文件(.img)的下载链接,同时也提供最新的源代码。Doxygen
GUI提供了Mac下的用户界面,比起命令行方式要更易于使用,其界面如下图:
![](http://hi.csdn.net/attachment/201103/3/0_1299145342fMd8.gif)
Figure 3:
Doxygen GUI
该界面列出了生成文档的必须步骤。第1步是配置使用Doxygen的模式
:Wizard向、Expert、Load。Wizard(向导模式)对于不太熟练的人更容易些,但通常使用Expert(专家模式)更加灵活。Load(导入模式)则允许使用已有的配置文件进行工作。当你改变设置之后,点击Save按钮并选择文件地址即可按指定文件名保存配置文件。接下来,指定源代码目录。然后,点Start按钮开始生成文档。
现在,可以来看看如何创建文档集了。
Generating a Doc Set
用Doxygen GUI创建文档集很简单。在下图中,显示的是Expert模式的Html设置标签。大部分设置保持默认就可以了,但Output(输出)必须指定。注意勾选Generate_html选项。确认勾选了Generate_docset选项。Docset_feedname的值会在Xcode的documentation窗口显示,所以哪怕你并不是想要创建一个RSS
feed文档集,也要在这里填上一个有意义的名字。使用公司名+产品名的反DNS方式命名Docset_bundle_id。
![](http://hi.csdn.net/attachment/201103/3/0_1299145610q8uU.gif)
Figure 4:
配置
Doxygen
接着,点图3中的Start按钮,Doxygen将根据一个Makefile文件生成HTML文档。用这个Makefile文件运行“make
install”命令,Doxygen会将HTML文档打包、安装为可以在Xcode documentation窗口中打开的文档集。
注:Xcode在目录
/Users/$USER/Library/Developer/Shared/Documentation/DocSets/
下查找文档集,其他的文档集查找目录列在<文档集指南>中了。
使用Xcode生成文档集
另一种创建文档集的方法是在Xcode项目中创建。为此,需要在Xcode项目中增加一个Build
Phase Script。Xcode把它叫做“Run Script Build Phase”。图5显示了添加“Build Phase Script”菜单。图6中,在target下高亮显示的就是一个Run
Script Phase。
![](http://hi.csdn.net/attachment/201103/3/0_1299145670Xsh3.gif)
Figure 5:
在
Xcode
中添加一个
Run Script Build Phase
![](http://hi.csdn.net/attachment/201103/3/0_1299145732jkMK.gif)
Figure 6:
Run Script Build Phase
添加完成后,双击该“Run Script Build Phase”,显示脚本编辑窗口。复制列表2中的脚本到脚本窗口中,结果如图7所示。
Listing 2:
Doc Set Build Script
#
Build the doxygen documentation for the project and load the docset into
Xcode.
#
Build the doxygen
documentation for the project and load the docset into Xcode.
#
Use the following to
adjust the value of the $DOXYGEN_PATH User-Defined Setting:
#
Binary
install location: /Applications/Doxygen.app/Contents/Resources/doxygen
#
Source build
install location: /usr/local/bin/doxygen
#
If the config file
doesn't exist, run 'doxygen -g $SOURCE_ROOT/doxygen.config' to
#
a get default file.
if ! [ -f $SOURCE_ROOT/doxygen.config ]
then
echo doxygen config file
does not exist
$DOXYGEN_PATH -g
$SOURCE_ROOT/doxygen.config
fi
#
Append the proper
input/output directories and docset info to the config file.
#
This works even though
values are assigned higher up in the file. Easier than sed.
cp $SOURCE_ROOT/doxygen.config $TEMP_DIR/doxygen.config
echo "INPUT = $SOURCE_ROOT" >> $TEMP_DIR/doxygen.config
echo "OUTPUT_DIRECTORY = $SOURCE_ROOT/DoxygenDocs.docset"
>> $TEMP_DIR/doxygen.config
echo "GENERATE_DOCSET
= YES" >>
$TEMP_DIR/doxygen.config
echo "DOCSET_BUNDLE_ID
=
com.mycompany.DoxygenExample" >> $TEMP_DIR/doxygen.config
#
Run doxygen on the
updated config file.
#
Note: doxygen creates a
Makefile that does most of the heavy lifting.
$DOXYGEN_PATH $TEMP_DIR/doxygen.config
#
make will invoke
docsetutil. Take a look at the Makefile to see how this is done.
make -C $SOURCE_ROOT/DoxygenDocs.docset/html install
#
Construct a temporary
applescript file to tell Xcode to load a docset.
rm -f $TEMP_DIR/loadDocSet.scpt
echo "tell application /"Xcode/"" >>
$TEMP_DIR/loadDocSet.scpt
echo "load documentation set with path
/"/Users/$USER/Library/Developer/Shared/Documentation/DocSets//""
>>
$TEMP_DIR/loadDocSet.scpt
echo "end tell" >> $TEMP_DIR/loadDocSet.scpt
#
Run the load-docset
applescript command.
osascript $TEMP_DIR/loadDocSet.scpt
exit 0
![](http://hi.csdn.net/attachment/201103/3/0_1299145796gGtd.gif)
![](file:///Users/kmyhy/Library/Caches/TemporaryItems/msoclip/0/clip_image002.png)
Figure 7:
输入或拷贝脚本到脚本窗口
你也许注意到了,脚本中使用了一个指向Doxygen执行文件目录的变量。这是必须的,因为Doxygen的二进制安装和源代码安装的
安装路径是不同的,正如脚本开头所述。图8显示了Target在使用 Get Info 命令后显示的信息.
![](http://hi.csdn.net/attachment/201103/3/0_12991458834SxU.gif)
Figure 8:
Target
的
Info
窗口
在build面板,“User-Defined Settings”菜单可以设置环境变量,从而可以用于编译过程中。图9显示如何进行设置。
![](http://hi.csdn.net/attachment/201103/3/0_1299145965b3bp.gif)
![](file:///Users/kmyhy/Library/Caches/TemporaryItems/msoclip/0/clip_image002.png)
Figure 9:
添加一个
User-Defined
Setting
图10, 把 Doxygen 二进制文件所在目录添加到环境变量。
![](http://hi.csdn.net/attachment/201103/3/0_1299146031selV.gif)
Figure 10:
设置
Doxygen
目录
编译Xcode项目。在Run Script Phase执行后,会生成文档集。编译结果如图11。
![](http://hi.csdn.net/attachment/201103/3/0_12991460862Z6r.gif)
Figure 11:
编译结果窗口
Doxygen的可配置性很好,但要创建Xcode可以打开和搜索的文档集并不需要进行太多的设置。列表2的脚本在别的Xcode项目中仍然可以使用,但需注意以下几点:
使用Doxygen创建文档集的第一步是需要创建一个Doxygen配置文件——它告诉Doxygen关于输出路径。在脚本里我们用doxygen
–g命令生成了一个默认的配置文件 。
默认配置文件有的地方需要修改。在脚本里我们简单地在配置文件后面添加新的设置。这样虽然也行,但可能不符合美学观点。
也许用sed编辑是一种更优雅的做法,它需要写更多的代码,却没有人去看配置文件。
该脚本生成了一个AS脚本,让Xcode打开新的文档集,从而你可以查找类、接口或者方法名,如图12所示。
![](http://hi.csdn.net/attachment/201103/3/0_1299146136NH7h.gif)
Figure 12:
新的文档集
注:如果文档集没有相应的feed URL,会在文档集名称旁有一个Subscribe按钮。
Doxygen是高度可配置的,并可生成多种格式的文档。这仅仅是生成HTML文档集的例子,如果你需要生成其他格式的配置和Makefiles文件,或者你想体验一下Doxgen最新的源代码版本,请浏览Doxygen网站,那里提供了Doxygen的下载、编译及安装指南。
其他信息
本文中的技术需要用到Doxygen。
ADC Reference Library
文档中列出的下列资源将是有用的
:
Documentation Set Guide
Xcode User Guide
以及 Doxygen 相关资源:
Doxygen home page
SourceForge project page
相关文章推荐
- 使用Doxgen创建Xcode文档集
- 使用Doxgen创建代码文档
- 使用Doxygen创建Xcode文档集(上)
- Creating Your Own Document Management System With SharePoint 使用SharePoint创建你自己的文档管理系统
- 使用SandCastle创建.Net帮助文档
- IOS xcode使用自带模板Tab bar Controller创建主页
- JavaFX文档(12)掌握FXML——4使用FXML来创建自定义控件
- XCode帮助文档离线使用
- 使用XmlDocument创建XML文档及增加删除更新节点
- [技巧]使用Xcode集成的HeaderDoc自动生成注释和开发文档 推荐
- xcode4.2下创建及使用静态库
- CocoaPods的使用(xcode创建的IOS应用中引入第三方类库:在同一目录下pod install/update)
- [翻译]使用Swift在Xcode中创建自定义控件
- 使用DOM创建和操作XML文档
- Xcode使用介绍之一:Xcode简介+创建App应用
- 在.NET 3.5 平台上使用LINQ to SQL创建三层/多层Web应用系统(源代码下载和PDF文档下载)
- graph-tool文档(一)- 快速开始使用Graph-tool - 1.创建和操纵图
- Itext 使用入门 之 创建pdf 文档 附中文解决方案
- 使用C#在Excel文档中创建图表
- 影子侠开发者蛋仔-谷歌官方文档之使用Tabs创建Swipe视图