使用Doxgen创建Xcode文档集

文档集为Xcode开发者提供了一个查找各种文档的便捷方式，包括：API、指南、教程、Q/A、示例代码及其他。
许多开发者都用过苹果文档集，如下图所示：



Figure 1:



Xcode中的苹果文档集

在Xcode3.0中，通过Xcode的Documentation窗口，可以集成苹果文档集之外的文档集。这样，可以想苹果文档集一样，使用Xcode的Document
Browser浏览这些文档。此外，还可象API文档一样和Xcode的搜索助手集成，如下图所示，当代码编辑器中选择代码时，可以提示API文档内容和编译设置。点击相应的符号链接，可以跳转到对应的文档。



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下的用户界面，比起命令行方式要更易于使用，其界面如下图：



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。



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。



Figure 5:



在

Xcode

中添加一个

Run Script Build Phase



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





Figure 7:



输入或拷贝脚本到脚本窗口

你也许注意到了，脚本中使用了一个指向Doxygen执行文件目录的变量。这是必须的，因为Doxygen的二进制安装和源代码安装的
安装路径是不同的，正如脚本开头所述。图8显示了Target在使用 Get Info 命令后显示的信息.



Figure 8:



Target

的

Info

窗口

在build面板，“User－Defined Settings”菜单可以设置环境变量，从而可以用于编译过程中。图9显示如何进行设置。





Figure 9:



添加一个

User-Defined
Setting

图10, 把 Doxygen 二进制文件所在目录添加到环境变量。



Figure 10:



设置

Doxygen

目录

编译Xcode项目。在Run Script Phase执行后，会生成文档集。编译结果如图11。



Figure 11:



编译结果窗口

Doxygen的可配置性很好，但要创建Xcode可以打开和搜索的文档集并不需要进行太多的设置。列表2的脚本在别的Xcode项目中仍然可以使用，但需注意以下几点：

使用Doxygen创建文档集的第一步是需要创建一个Doxygen配置文件——它告诉Doxygen关于输出路径。在脚本里我们用doxygen
–g命令生成了一个默认的配置文件 。

默认配置文件有的地方需要修改。在脚本里我们简单地在配置文件后面添加新的设置。这样虽然也行，但可能不符合美学观点。
也许用sed编辑是一种更优雅的做法，它需要写更多的代码，却没有人去看配置文件。

该脚本生成了一个AS脚本，让Xcode打开新的文档集，从而你可以查找类、接口或者方法名，如图12所示。



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