使用Doxgen创建Xcode文档集

 

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

 

Figure 1: Xcode中的苹果文档集

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

 

 

Figure 2: Xcode中的搜索助手

Note: 使用菜单 Help > Show/Hide Research Assistant 开启搜索助手.

本文显示了如何生产文档，把文档封装到文档集并放到Xcode能认识的路径下。另一种方法是把文档集发布为feed（基于RSS订阅机制）。RSSfeed常用于各种规模的开发团队，用RSS feed方式在Xcode安装文档集，你能轻易地自动接收文档集的更新。

正如文档集指南（本文后附有链接）所述，文档集有着定义良好的结构。为避免完全使用手工制作的繁琐，开源的Doxygen能从你的源代码中自动产生文档——包括生成html、打包和部署，从而使你把精力放到文档的内容上。

Doxygen

Doxygen从源代码生成文档。它能生成多种格式的在线或离线文档。它支持c/c++，ObjectiveC，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）的下载链接，同时也提供最新的源代码。DoxygenGUI提供了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窗口显示，所以哪怕你并不是想要创建一个RSSfeed文档集，也要在这里填上一个有意义的名字。使用公司名+产品名的反DNS方式命名Docset_bundle_id。

 

Figure 4: 配置 Doxygen

接着，点图3中的Start按钮，Doxygen将根据一个Makefile文件生成HTML文档。用这个Makefile文件运行“makeinstall”命令，Doxygen会将HTML文档打包、安装为可以在Xcode documentation窗口中打开的文档集。

注：Xcode在目录/Users/$USER/Library/Developer/Shared/Documentation/DocSets/下查找文档集，其他的文档集查找目录列在<文档集指南>中了。

使用Xcode生成文档集

另一种创建文档集的方法是在Xcode项目中创建。为此，需要在Xcode项目中增加一个BuildPhase Script。Xcode把它叫做“Run Script Build Phase”。图5显示了添加“Build Phase Script”菜单。图6中，在target下高亮显示的就是一个RunScript 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 intoXcode. 

#  Build the doxygendocumentation for the project and load the docset into Xcode.

 

#  Use the following toadjust the value of the $DOXYGEN_PATH User-Defined Setting:

#    Binaryinstall location: /Applications/Doxygen.app/Contents/Resources/doxygen

#    Source buildinstall location: /usr/local/bin/doxygen

 

#  If the config filedoesn't exist, run 'doxygen -g $SOURCE_ROOT/doxygen.config' to

#   a get default file.

 

if ! [ -f $SOURCE_ROOT/doxygen.config ]

then

  echo doxygen config filedoes not exist

  $DOXYGEN_PATH -g$SOURCE_ROOT/doxygen.config

fi

 

#  Append the properinput/output directories and docset info to the config file.

#  This works even thoughvalues 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 theupdated config file.

#  Note: doxygen creates aMakefile that does most of the heavy lifting.

 

$DOXYGEN_PATH $TEMP_DIR/doxygen.config

 

#  make will invokedocsetutil. Take a look at the Makefile to see how this is done.

 

make -C $SOURCE_ROOT/DoxygenDocs.docset/html install

 

#  Construct a temporaryapplescript 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-docsetapplescript 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-DefinedSetting

图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