文档集为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 文档中列出的下列资源将是有用的 ：
以及 Doxygen 相关资源:
5956
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
