使用appledoc 生成技术API文档具体解释
一、 首先安装 appledoc
- 第一步:使用终端命令进行下载安装
git clone git://github.com/tomaz/appledoc.git cd ./appledoc sudo sh install-appledoc.sh
上面步骤运行之后。上面三个步骤都是正常运行的。文件有点大,下载会慢一点,我们看下效果图:
成功安装之后的图片
假设出现 INSTALL SUCCEEDED 则说明我们成功安装了。
- 以下进行第二步:安装之后我们进行一个简单的验证
appledoc --version //用法能够输入命令 appledoc --help
二、用法
- 第一步:使用终端进入代码文件夹:
-
直接拖拽我们的project到终端,然后回车一下
- 或者使用
cd+"项目名字文件夹"
同1 - 以上两种方法都能够进入到我们的project根文件夹
- 第二部:
project-name: 项目名字
project-company: 公司名称
使用命令:
//以下这个会运行错误 1. appledoc --project-name 你的工程名字 --project-company 公司名 ./(导出路径,这里是指根文件夹) path所要导出的文档的类文件夹 错误提示是:AppledocException: At least one directory or file name path is required 2. 正确的运行命令: appledoc --no-create-docset --output ~/doc --project-name "Your Project Name" --company-id "com.yourcommpany" --project-company "Your Company" ./ 3. appledoc --project-name DiskSizeDemo --project-company "ray" --company-id aaaa --output ./apple ~/DeskTop/RYDemoTest/DiskSizeDemo/DiskSizeDemo/doc/ 最后一个命令须要5个參数: 1. 工程名字 2. 公司名字 3. 公司ID 4. 生成结果出书路径 5. 扫描那个路径下的类 运行成功都能够在我们对应的地址下找到 4. appledoc -o ./doc --project-name DiskSizeDemo --project-company feel . appledoc会扫描当前路径下的全部文件,然后生成好文档放到doc文件夹下。你也能够用appledoc –help查看全部可用的參数。 使用的时候一定要注意最后一个路径。别忘了。不然会提示错误。最后一个是导出扫描到的文件
上面执行成功会出现以下截图
我们能够在 电脑的 Users 下找到raybon 这个目录[/p]
- project中使用
-
我们先新建一个project,Demo 就是我们实验的測试DiskSizeDemo
- 选择菜单File->New File -> Target :
这里都能看懂吧
加入之后我们在去设置界面
QQ20160317-2@2x.png 通过我们新添加的Run Script
加入一下脚本[/p]
#appledoc Xcode script # Start constants company="abc"; companyID="com.abc"; companyURL="http://abc.com"; target="iphoneos"; #target="macosx"; outputPath="~/help";//输出地址 # End constants /usr/local/bin/appledoc \ --project-name "${PROJECT_NAME}" \ --project-company "${company}" \ --company-id "${companyID}" \ --docset-atom-filename "${company}.atom" \ --docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \ --docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \ --docset-fallback-url "${companyURL}/${company}" \ --output "${outputPath}" \ --publish-docset \ --docset-platform-family "${target}" \ --logformat xcode \ --keep-intermediate-files \ --no-repeat-first-par \ --no-warn-invalid-crossref \ --exit-threshold 2 \ "${PROJECT_DIR}"
然后选择以下
QQ20160317-3@2x.png
选择好之后我们run 一下
project中我们新建的有个Doc.h 和Doc.m 的类
代码例如以下
#import <Foundation/Foundation.h> @interface Doc : NSObject /*! @brief this is comment. */ - (void)run; /*! @brief查询数据方法 */ - (void)seekMethod; @end
我们假设run 之后能够在本地找到一个 dorset-install.txt 文件
QQ20160317-4@2x.png 我们打开HTML 下的index.html [/p]
QQ20160317-5@2x.png
看到了吧,是不是我们常常看到的技术文档
我们假设想要导出这样的格式,凝视须要依照规定的来,这个我不清楚为什么要这样子,有知道的还望留言一下。在此谢过大神。
我去查询的资料是支持一下三种凝视格式:
1. /*! this a test . */ 2. /** this a comment. */ 3. /// this is a long comment. */
常常使用的标签:
@brief : 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描写叙述信息。举例:@discusstion: 用它来写一段详尽的描写叙述。假设须要你能够加入换行。
@param:通过它你能够描写叙述一个 method 或 function的參数信息。你能够使用多个这样的标签。 @return: 用它来制定一个 method 或 function的返回值。
@see: 用它来指明其它相关的 method 或 function。你能够使用多个这样的标签。
@sa:同上 @code : 使用这个标签,你能够在文档其中嵌入代码段。
当在Help Inspector其中查看文档时,代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。
@remark : 在写文档时,用它来强调不论什么关于代码的特殊之处。
/*! @brief This property knows my name. */ @property (nonatomic, strong) NSString *myName;
这样的凝视在调用的时候也会有提示,我们如今经常使用的VVDocument-Xcode 凝视插件,是一样的原理
记录文件经常使用标签:
让我介绍一些当你在记录一个文件时会用到的新标签: @file: 使用这个标签来指出你正在记录一个文件(header 文件或不是)。到此我们就结束了,详细其它使用也能够參考以下这个假设你将使用Doxygen来输出文档。那么你最好在这个标签后面紧接着写上文件名称字。
它是一个top level 标签。 @header: 跟上面的类似,可是是在 HeaderDoc中使用。当你不使用 Doxygen时。不要使用上面的标签。 @author:用它来写下这个文件的创建者信息 @copyright: 加入版权信息 @version: 用它来写下这个文件的当前版本号。假设在project生命周期中版本号信息有影响时这会非常重要。 再一次的,我仅仅给出最经常使用的标签。自己查看说明文档了解很多其他标签信息。
@class: 用它来指定一个class的凝视文档块的开头。
它是一个top level标签,在它后面应该给出class名字。 @interface: 同上 @protocol: 同上两个一样。仅仅是针对protocols @superclass: 当前class的superclass @classdesign: 用这个标签来指出你为当前class使用的不论什么特殊设计模式(比如,你能够提到这个class是不是单例模式或者类似其他的模式)。
@coclass: 与当前class合作的另外一个class的名字。 @helps: 当前class帮助的class的名字。 @helper: 帮助当前class的class名字。 使用HeaderDoc生成文档
headerdoc2html
Xocde 高速生成文档
官方使用;
查询生成的HTML页面:
~/Library/Developer/Shared/Documentation/DocSets/
本文主要使用了appledoc
其次就是 headerdoc ,我測试了两种,仅仅是认为appledoc 的更好一些。看着界面更舒服一些。
文/Raybon_lee(简书作者)
原文链接:http://www.jianshu.com/p/65f1afdb9445
著作权归作者全部,转载请联系作者获得授权,并标注“简书作者”。
- iOS使用appledoc 生成技术API文档详解
- iOS使用appledoc 生成技术API文档详解
- 使用appledoc 生成技术API文档详解
- 使用appledoc 生成技术API文档详解
- PHP的学习--使用PhpDocumentor 2生成API文档
- 使用Objective-C的文档生成工具:appledoc
- HighCharts 具体使用及API文档说明
- Ubuntu12.04下使用doxygen生成API文档
- java小例子:使用javadoc工具生成API文档
- 使用eclipse 生成自己项目的API帮助文档
- [shiro学习笔记]第四节 使用源代码生成Shiro的CHM格式的API文档
- ns3使用doxygen生成离线api文档
- HighCharts 具体使用及API文档说明
- 【Java】使用Eclipse生成API文档
- HighCharts 具体使用及API文档说明
- 使用Objective-C的文档生成工具:Appledoc
- 使用Objective-C的文档生成工具:appledoc
- HighCharts 具体使用及API文档说明
- 在flex4中使用asdoc生成api文档
- 使用javadoc生成API网页文档