建立iOS专属文档之Objective-C API文档生成器

appledoc

Objective-C API文档生成器

参考文

iOS使用appledoc 生成技术API文档详解
iOS使用appledoc来创建开发文档（装逼使用）
iOS - appledoc 文档添加

再学习Android时，重温JAVA发现，JAVA能生成API文档，心里突然想：不对啊，我大iOS怎么可能没有呢？于是......

安装

git clone git://github.com/tomaz/appledoc.git
cd appledoc 
sudo sh install-appledoc.sh

使用brew安装

brew install appledoc

验证

appledoc --version

我安装的版本: appledoc version: 2.2.1 (build 1334)

使用

方式一：

CD进入项目目录,复制粘贴下面命令

appledoc --project-name projectName --project-company abc ./

你会在你的项目目录中发现docset-installed.txt文件，内容如下

Documentation set was installed to Xcode!

Path: /Users/*****/Library/Developer/Shared/Documentation/DocSets/com.abc.myproject.projectName.docset
Time: 2018-01-27 09:32:14 +0000

这种方式简单粗暴，但想要格式出想要的，恐怕这一条是不够的。

方式二：

新建：New -> Target -> Cross-platform ->Aggregate
会在PROJECT下创建新文件

f60edb4b-f070-4673-9fb4-cd57c5da301d.png

63802900.png

在Build Phases 新建 Run Script 拷贝下面代码

我借鉴别人的。

#appledoc Xcode script
# Start constants

company="abc";
companyID="com.abc";
companyURL="http://www.abc.com";
target="iphoneos";
#target="macosx";
outputPath="../Documents";
# 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}"

问题

Command /bin/sh failed with exit code 127

可能也遇见了250

因为的Pods问题，我忽略了一个文件夹Pods文件夹。运行通过,每一行不能存在空行

--ignore ".../.../.../Pods" \

对于注释：XCode给定的快捷键option+command+/

/**
 公历类   【对类进行说明】
 */
@interface Solar : NSObject
/**
 *公历 日 【对属性进行说明】
 */
@property(assign) int solarDay;
/**
 *公历 月
 */
@property(assign) int solarMonth;
/**
 *公历 年
 */
@property(assign) int solarYear;
@end

/**
 完成点击
 @param model 结果
 */

-(void)complete:(DateModel *)model{
    //todo
}

基本操作已完成，接下来就是认真的熟悉每一个命令

help

Find more help and tips online:

• http://appledoc.gentlebytes.com/
• http://tomaz.github.com/appledoc/

• [b] 布尔参数，不使用任何值，使用-no-前缀来否定。
• [*] 表示参数接受占位符字符串

path[路径]

简	全	说明
-o	--output	输出路径
-t	--templates	模板路径
-s	--include	包含的静态Doc的路径
-i	--ignore	需要被忽略的路径
-	--docset-install-path	DocSet安装路径
-x	--exclude-output	从输入排除的路径
-	--index-desc	文件包括主索引描述

PROJECT INFO[项目信息]

简	全	说明
-p	--project-name	项目名称
-v	--project-version	项目版本
-c	--project-company	公司名称
-	--company-id	公司ID

OUTPUT GENERATION[生成输入]

简	全	说明
-h	--create-html	[b]创建HTML
-d	--create-docset	[b]创建文件设置
-n	--install-docset	[b]给Xcode安装文件
-u	--publish-docset	[b]准备发行DocSet
-	--html-anchors	[*]DocSet的HTML版本的作者
-	--clean-output	[b]在开始前删除输出路径的内容！！小心！！

OPTION[选项]

简	全	说明
-	--keep-intermediate-files	[b] 在输出路径中保留中间文件
-	--keep-undocumented-objects	[b] 保持无证对象
-	--keep-undocumented-members	[b] 保持非法成员
-	--search-undocumented-doc	[b] 文档搜索非法成员
-	--repeat-first-par	[b] 在成员文档中重复第一段
-	--preprocess-headerdoc	[b] 预处理头文件注释——仅为10.7！
-	--print-information-block-titles	[b] 打印信息块的标题。“注:”、“警告:“,等等。
-	--use-single-star	[b]为加粗标志物使用一颗单星
-	--merge-categories	[b] 为类合并类别
-	--merge-category-comment	[b] 为类合并类别标识
-	--keep-merged-sections	[b] 保持合并分类部分
-	--prefix-merged-sections	[b] 前缀合并部分和类别名称
-	--explicit-crossref	[b] 显式缺省交叉引用模板的快捷方式
-	--use-code-order	[b] 按照输入文件中指定的顺序来排序
-	--crossref-format	[b]交叉引用模板正则表达式
-	--exit-threshold	[b]退出代码阈值以下，返回0
-	--docs-section-title	[b]文档部分的标题(默认为“编程指南”

WARINGS[警告]

简	全	说明
-	--warn-missing-output-path	[b] 如果没有给出输出路径，则警告
-	--warn-missing-company-id	[b] 如果没有给出公司ID，则警告
-	--warn-undocumented-object	[b] 对非法对象警告
-	--warn-undocumented-member	[b] 对非法成员警告
-	--warn-empty-description	[b] 空描述块上的警告
-	--warn-unknown-directive	[b] 对未知指令或格式发出警告
-	--warn-invalid-crossref	[b] 警告无效交叉引用
-	--warn-missing-arg	[b] 关于缺少方法参数文档的警告
-	--warn-unsupported-typedef-enum	[b] 对不支持的typedef枚举发出警告

MISCELLANEOUS[杂项]

简	全	说明
-	--docset-bundle-id	[*] DocSet包ID
-	--docset-bundle-name	[*] DocSet bundle名称
-	--docset-desc	[*] DocSet 描述
-	--docset-copyright	[*] DocSet 版权信息
-	--docset-feed-name	[*] DocSet feed 名称
-	--docset-feed-url	[*] DocSet feed URL
-	--docset-feed-formats	DocSet feed 格式. 由一个逗号分开 [atom,xml]
-	--docset-package-url	[*] DocSet package (.xar) URL
-	--docset-fallback-url	[*] DocSet 回退 URL
-	--docset-publisher-id	[*] DocSet出版商 ID
-	--docset-publisher-name	[*] DocSet出版商名称
-	--docset-min-xcode-version	[*] DocSet 最小. Xcode版本
-	--docset-platform-family	[*] DocSet 平台
-	--docset-cert-issuer	[*] DocSet c证书发行机构
-	--docset-cert-signer	[*] DocSet 签名者证书
-	--docset-bundle-filename	[*] DocSet 包 文件名
-	--docset-atom-filename	[*] DocSet原始 feed 文件名
-	--docset-xml-filename	[*] DocSet xml feed 文件名
-	--docset-package-filename	[*] DocSet 包 (.xar,.tgz) 文件名. 离开了扩展。这将根据生成的包来添加

DOCUMENTATION SET INFO[文档设置信息]

简	全	说明
-	--logformat	Log 格式 [0-3]
-	--verbose	Log 冗余等级 [0-6,xcode]
-	--version	显示版本和通道
-	--help	显示帮助和通道

---

• - %PROJECT 取代 --project-name
• - %PROJECTID 取代标准 --project-name
• - %VERSION 取代 --project-version
• - %VERSIONID 取代 --project-version
• - %COMPANY 取代 --project-company
• - %COMPANYID 取代 --company-id
• - %YEAR 取代当前年份 (format yyyy)
• - %UPDATEDATE 取代当前日期 (format yyyy-MM-dd)
• - %DOCSETBUNDLEFILENAME 取代 --docset-bundle-filename
• - %DOCSETATOMFILENAME 取代 --docset-atom-filename
• - %DOCSETPACKAGEFILENAME 取代 --docset-package-filename