iOS appledoc自动生成API文档

一、安装过程

• 第一步：下载安装

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

  稍等一会，安装OK。
• 第二步：安装验证：

  appledoc --version

---

二、使用

• 第一步：进入代码所在文件夹：(你忘了？好吧我告诉你怎么进)，进入终端：

  cd + “文件夹目录”

• 第二步：
  name:项目名称
  company：公司名称
  这俩个自己可以替换一下

  appledoc --project-name MyProject --project-company ibireme ./

  之后你会看到你的文件夹下会多出一个文件，稍后会说这个文件的作用：
  
  
  

  
  
  
  如果想了解更多，可以查看帮助：

  appledoc --help

• 第三步：集成进我们自己的工程
  • 1、在你的工程中创建新的 Target，注意这里要选择 Other 中的 Aggregate，如图
    
    
    

    
    
    
    
    
    

    
    
  • 2、在我们新创建的 Target 中的 Buid Phases 中添加 Run Script，
    
    
    

    
    
  • 3、 打开Run Script，Shell 下面的文档区域添加这样的模板：

    #appledoc Xcode script  
    # Start constants  
    company="ACME";  
    companyID="com.ACME";
    companyURL="http://ACME.com";
    target="iphoneos";
    #target="macosx";
    outputPath="~/help";
    # 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}"

  • 4、Xcode 左上方选择这个 Target ，然后 Build 编译。
  • 5、文档就会编译好并且自动安装进 Xcode 了（重启Xcode生效）。
  • 6、那么编译之后我们就可以去查看它了，那么在哪里可以看到呢？这时我们就可以用之前生成的 docset-installed.txt文件啦，打开它：看到以一个 Path 了吧：直接复制，然后在 Finder 中前往文件夹：
    
    
    

    文件目录.png
  • 7、如果顺利的话我们就会看到这里啦：这个就是你生成的包文件，右键 --> 显示包内容你就会看到你的注释文件们啦，自己好好找喽。
    ![Uploading 内容_278572.png . . .]
    
    
    

    包文件.png
    
    
    
    

    内容.png

  • ---

    三、关于 appledoc 的一些问题 （只有 .h文件的注释符合标准才能够生成对应文档，否则对应部分文档为空）
    

  • • appledoc 支持的注释类型

      /// 这是单行注释。
      /** 这也是单行注释 */
      /*! 同样是单行注释 */
      /** 这也是单行注释，
      *  第二行会接上第一行。
      */

    • 用法示例

      /** 第一行是类的简介
      在简介的下面,就是类的详细介绍了。
      没有间隔换行会被消除，就像Html那样。
      下面是常用的markdown语法
      - - -
      无序列表: (每行以 '*'、'-'、'+' 开头):
      * this is the first line
      * this is the second line
      * this is the third line
      有序列表: (每行以 1.2.3、a.b.c 开头):
      a. this is the first line
      b. this is the secode line
      多级列表:
      * this is the first line
        a. this is line a
        b. this is line b
      * this is the second line
        1. this in line 1
        2. this is line 2
      标题:
      # This is an H1
      ## This is an H2
      ### This is an H3
      #### This is an h4
      ##### This is an h5
      ###### This is an H6
      链接:
      普通URL直接写上，appledoc会自动翻译成链接: http://blog.ibireme.com
      [这个](http://example.net/) 链接会隐藏实际URL.
      表格:
      | header1 | header2 | header3 |
      |---------|:-------:|--------:|
      | normal  |  center |  right  |
      | cell    | cell    | cell    |
      引用:
      这里会引用到方法 `someMethod:`，这里会引用到类 `YYColor`
      这里会引用到一个代码块
         void CMYK2RGB(float c, float m, float y, float k, 
                        float *r, float *g, float *b) {
             *r = (1 - c) * (1 - k);
             *g = (1 - m) * (1 - k);
             *b = (1 - y) * (1 - k);
         }
      @since iOS5.0
      */
      @interface AppledocExample : NSObject
      ///这里是属性的说明
      @property (nonatomic, strong) NSString *name;
      /** 
      @brief 这里是方法的简介。该Tag不能放到类注释里。
      @exception UIColorException 这里是方法抛出异常的说明
      @see YYColor
      @see someMethod:
      @warning 这里是警告，会显示成蓝色的框框
      @bug 这里是bug，会显示成黄色的框框
      @param red   这里是参数说明1
      @param green 这里是参数说明2
      @param blue   这里是参数说明3
      @return  这里是返回值说明
      */
      - (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;
      - (void)someMethod:(NSString *)str;
      @end