【作者前言】: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
!!!概率性极低的雷区:安装过程中如遇到 CommandLineTools错误
,如图:
则直接如图勾选后即可
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
执行完脚本后...
我们的工程文件目录下就会生成如下结构的文件目录...
6)打开index.html,见证装逼时刻...(O(∩_∩)O~)
!!!Attention---注释要合规,保持良好的代码写作习惯,则会自动生成对应的文档!!!
3.列举一些Beautiful的注释,更多就自己摸索吧...
/**
@brief -->简要描述
@param -->用于参数说明
@see -->可见的链接性说明,文档中可对应链接到内容 一般可用于注释枚举属性的类型
@discussion -->详细说明 提醒信息
@warning -->警告内容
@bug -->bug内容
@return -->返回值说明
*/
效果如图: