appledoc生成注释文档

起源

公司里有在推进代码注释，但同事注释的积极性并不高，一大原因就是，注释得再好，了解业务时，也不可能让其它同事点进代码一个个看，这种方式太繁琐了。只有导出对应的标准文档来，才有注释的动力。

appledoc

查阅发现了appledoc这个好用工具，具体介绍见ibireme的用appledoc生成文档。

shell工具

上面帖子中介绍了安装方式及基本使用，但个人觉得，还是写成shell脚本的形式使用，更加方便，so，见下文。

脚本功能

1. 自动判定是否已安装appledoc，如未安装提示安装。
2. 注释导出环节，自动判定仅为当前shell脚本目录添加注释。所以只需要在project同级文件夹下复制一份此脚本即可。
3. 生成文档为html格式，导出目录为桌面/我的注释/文件夹。
4. html注释生成后，自动浏览器打开文档。

使用方式

1. 打开终端，创建代码注释脚本

cd ~/desktop
touch 代码注释
chmod 777 代码注释

会发现代码注释变会小黑框。

2. 使用文本编辑器打开代码注释
   复制下面脚本内容，粘贴，然后command+s保存。

# ############################ 安装appledoc ############################

which appledoc
is_installed=$?
# 如果未安装，则安装
if [ ${is_installed} == 1 ]
then
    echo '您尚未安装appledoc，不能生成项目注释。是否安装？同意回复Y'
    read is_agree

    if [ ${is_agree} == 'Y' ]
    then
        echo "正在安装appledoc。。。"
        git clone git://github.com/tomaz/appledoc.git
        cd ~/appledoc
        sudo sh install-appledoc.sh
        echo "appledoc安装成功"
    else
        echo "未同意安装appledoc，退出"
        exit
    fi
else
    echo 'appledoc已安装'
fi

# ############################ 注释文档导出 ############################

# #:表示从左开始算起，并且截取第一个匹配的字符
# ##:表示从左开始算起，并且截取最后一个匹配的字符
# %:表示从右开始算起，并且截取第一个匹配的字符
# %%:表示从右开始算起，并且截取最后一个匹配的字符

# 记录个人桌面
cd ~
DESKTOP="`pwd`/desktop"
echo $DESKTOP

# 当前可执行文件路径/文件夹名称/导出html路径
cd $(dirname $0)
project_path=`pwd`
project_name="${project_path##*/}"
export_path="${DESKTOP}/我的注释/${project_name}"

echo "$project_path>>>$project_name>>>$export_path"

# 如果不存在此文件夹，则创建
if [ ! -d ${export_path} ];then
mkdir -p ${export_path}
fi

# 开始生成html注释
appledoc --no-create-docset -p ${project_name} -c 'zz代码注释' -i ${project_path}/Pods -o ${export_path} ./

# 打开文件
HTML_PATH="${export_path}/html/hierarchy.html"
open ${HTML_PATH}
echo '已open'

ok，可以把代码注释copy进个人的项目文件夹下，双击验证下成果了。
注意: 如果第一次使用appledoc，会有一个安装过程，耗费比较长的时间，然后进入注释导出步骤。
安装一次，以后再使用，就直接走注释环节了。
小tip：如果想要shell脚本执行完成后，自动关闭终端框，可在终端设置：终端-->偏好-->描述文件-->shell-->当shell退出时/关闭窗口。

界面效果

appledoc注释条理果然很清晰

appledoc注释

---

一些问题

1. 目前想要忽略一些目录，如Pods，用--ignore path竟然不生效，正在查找原因。希望知道的小伙伴告知下原因
2. shell个人所写，遇到bug可以反馈给我。