【作者前言】：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