【教程】Step By Step,利用Xcode生成标准项目文档

  转自： http://www.cocoachina.com/bbs/read.php?tid=91097

在写 代码的时候，如果按照一定的规范在头 文件里写上注释的话，
就可以利用 Xcode的文档自动输出功能生成一份完整的HTML项目文档。
生成的格式和Apple Developer网站上的API文档几乎是一样的。
我们来看看如何利用Xcode生成项目文档。
步骤:
1. 在XCode里点击Project,然后点Add Target给项目添加一个TARGET

2. 在添加Target的弹出对话框里，选择Aggregate,点击Next,输入一个你喜欢的名字,点击Finish

3. 你会发现TARGETS下面多了一个项目，点击它，然后在右边点击BuildPhases标签，然后点击Add Build Phase并选择Add Run Script

4. Run Script添加成功后，点击它的下拉菜单，把以下代码拷贝到代码对话框里。

# shell script goes here
mkdir -p headerDoc
find ./HelloPhoneGap/Classes -name \*.h -print | xargs headerdoc2html -o headerDoc
gatherheaderdoc headerDoc
exit 0
注意：代码里的./HelloPhoneGap/Classes是你的类文件的保存的路径，请根据各自情况修改。

5. 在XCode左上角的Scheme里选定刚才生成的Target,然后点Run。
运行以后，在你的项目文件夹里，就会生成一个文档文件夹了。
这些自动生成的文档都是根据你在源代码里写的注释生成的。


下面就详细介绍一下各种能自动生成文档的注释
■ header : 头文件基本信息。这个用在每个源代码文件的头文件的最开头。
例如:

复制代码 /*! @header 这里的信息应该与该源代码文件的名字一致 @abstract 关于这个源代码文件的一些基本描述 @author Kevin Wu (作者信息) @version 1.00 2012/01/20 Creation (此文档的版本信息) */

■ class: 类信息。此注释用在类声明的开头。
例如:

复制代码 /*! @class @abstract 这里可以写关于这个类的一些描述。 */ @interface MyClass : NSObject { }

■ property: property的相关注释。

复制代码 /*! @property @abstract 这里可以写关于这个Property的一些基本描述。 */ @property (nonatomic,readonly) NSString *helloDocText_;

■ method: 函数(方法)的相关注释。

复制代码 /*! @method @abstract 这里可以写一些关于这个方法的一些简要描述 @discussion 这里可以具体写写这个方法如何使用，注意点之类的。如果你是设计一个抽象类或者一个 共通类给给其他类继承的话，建议在这里具体描述一下怎样使用这个方法。 @param text 文字 (这里把这个方法需要的参数列出来) @param error 错误参照 @result 返回结果 */ - (BOOL)showText:(NSString *)text error:(NSError **)error;

■ enum: enum的相关注释。

复制代码 /*! @enum @abstract 关于这个enum的一些基本信息 @constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag @constant HelloDocEnumDocDemoTagNumberOKButton OK按钮的Tag */ typedef enum HelloDocEnumDocDemo_{ HelloDocEnumDocDemoTagNumberPopupView = 100, HelloDocEnumDocDemoTagNumberOKButton, }HelloDocEnumDocDemo;

■ category: category的相关注释。

复制代码 /*! @category @abstract NSString的Category */ @interface KevinNSString (NSString)

■ protocol: protocol的相关注释

复制代码 /*! @protocol @abstract 这个HelloDoc类的一个protocol @discussion 具体描述信息可以写在这里 */ @protocol HelloDocDelegate ＜NSObject＞

以上列举的标准注释也许并不完善。
具体请参考 苹果的developer网站的API文档。
以上列举的标准注释全都在下面的头文件里，仅供参考。
HelloDoc.h


更加详细的内容，请参考我的网站上的原文：
http://kevin-wu.net/how-to-create-documentation-with-xcode/