iOS 开发_编写接口文档(appledoc实用篇)

【作者前言】:13年入圈,分享些本人工作中遇到的点点滴滴那些事儿,17年刚开始写博客,高手勿喷!以分享交流为主,欢迎各路豪杰点评改进!

1.应用场景:

编写类似于苹果官方文档的Html接口文档,做过SDK开发的朋友们应该很清楚appledoc的强大之处。这里不做过多解释,经过实际应用做比对,headerDoc(苹果自带)与appledoc,选择了后者。

2.实现目标:

实战层面上,真正的将appledoc使用起来,Get该项技能

实际使用上问题挺多,尤其Xcode9之后,普遍的方法会出现此错误:ERROR | !> xcrun: error: unable to find utility "docsetutil", not a developer tool or in PATH

借鉴了许多Stack Overflow,Github上的issue,尝试了许多,最终使用了本篇文章介绍的方法。

3.代码说明:

1.安装appledoc(推荐直接使用终端下载,依次执行命令即可)
1)git clone git://github.com/tomaz/appledoc.git
2)cd ./appledoc
3)sudo sh install-appledoc.sh

校验下是否安装成功?!

4)appledoc --version
image.png

!!!概率性极低的雷区:安装过程中如遇到 CommandLineTools错误,如图:

image.png

则直接如图勾选后即可


image.png
2.开始实战!!!

摒弃采用命令行创建doc文件等..以及Xcode内添加执行脚本的方式,而是采用最直接的方式:
终端->编写脚本->运行脚本->更新脚本从而规避docsetutil找不到等错误,更加方便维护!

1)来到对应的工程文件路径下

cd testAppledocDemo

2)在工程目下创建一个脚本,如myProDoc.sh

vim myProDoc.sh
使用vim命令可通过命令 i 直接进入编辑模式,更为快捷

3)编辑myProDoc.sh脚本
#!/bin/bash
appledoc \
#文档输出目录
--output ./apiDoc \                                       
#忽略.m文件,因.m中均为私有api和属性,开源的接口文档中理应忽略掉
-i *.m \                                                         
#工程的名字
--project-name "testAppledocDemo" \
#公司的名字
--project-company "Zyp" \
#不生成docset,直接输出html
--no-create-docset \
#没有注释的文件也输出html  -->目的是看到所有的文件
--keep-undocumented-objects \
#没有注释的属性和方法也输出到html  -->目的是看到所有的属性和方法
--keep-undocumented-members \
#没有注释的文件不提示警告
--no-warn-undocumented-object \
#没有注释的属性和方法不提示警告
--no-warn-undocumented-member \
#需要输出的文件路径  -->这里推荐最好直接为当前工程路径平级输出,便于维护和使用
./
4):wq 保存并退出
5)执行脚本

./myProDoc.sh
如遇权限错误 -bash: ./myProDoc.sh: Permission denied
则处理下脚本文件属性,使脚本具有执行权限
chmod +x myProDoc.sh

执行完脚本后...

我们的工程文件目录下就会生成如下结构的文件目录...


image.png
6)打开index.html,见证装逼时刻...(O(∩_∩)O~)

!!!Attention---注释要合规,保持良好的代码写作习惯,则会自动生成对应的文档!!!

3.列举一些Beautiful的注释,更多就自己摸索吧...
/**
 @brief     -->简要描述
 @param     -->用于参数说明
 @see       -->可见的链接性说明,文档中可对应链接到内容 一般可用于注释枚举属性的类型
 @discussion        -->详细说明 提醒信息
 @warning       -->警告内容
 @bug       -->bug内容
 @return        -->返回值说明
 */

效果如图:


image.png
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 203,772评论 6 477
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 85,458评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 150,610评论 0 337
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,640评论 1 276
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,657评论 5 365
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,590评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,962评论 3 395
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,631评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,870评论 1 297
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,611评论 2 321
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,704评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,386评论 4 319
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,969评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,944评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,179评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 44,742评论 2 349
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,440评论 2 342

推荐阅读更多精彩内容