ios 自动产生代码文档

select the Scheme drop down and change from AppledocTests to appledoc build target. Pretty simple unless you’re returning to cocoa coding

 个人感觉这个就和当年在。net／vs.net ide中一样，能够帮助产生帮助文件，而且格式还不错，关键是用的人是不是喜欢看帮助文件。

Installing appledoc

First we’ll need to install the appledoc tool. The easiest way to do this is to clone the source code from GitHub using the following command in the Terminal:

$ git clone git://github.com/tomaz/appledoc.git

admins-MacBook-Pro:Documents admin$ git clone git://github.com/tomaz/appledoc.git
Cloning into appledoc...
remote: Counting objects: 7975, done.
remote: Compressing objects: 100% (2271/2271), done.
remote: Total 7975 (delta 5850), reused 7668 (delta 5563)
Receiving objects: 100% (7975/7975), 3.56 MiB | 124 KiB/s, done.
Resolving deltas: 100% (5850/5850), done.
admins-MacBook-Pro:Documents admin$  ＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝

This will create a folder called appledoc on your local machine containing the latest version of the source code. Inside you will find the Xcode project. Just open it and compile the appledoc target. 打开然后编译这个项目

In order to make the tool generally available from the command line it must be copied to a location that’s included in the default search path. Personally I prefer to use /usr/local/bin but feel free to place it anywhere you like. 产生文件后，我们把可执行文件appdoc复制

You must also copy the contents of the Templates directory to one of the locations expected by the appledoc tool. This can be done from the command line using the following commands: 就是在下载下来的目录下有 templates目录，用于html的吧.把模版文件夹放置到 目录~library/applicaiton support下面

如果目录有空格，采用\ 在第一个空格处

在新的xcode 4下面，我们可以看到的是：

/Users/用户名/Library/Developer/Xcode/DerivedData/产品名称-fylcrwghjxojxcgaejhixgwinhus/Build/Products/ ／／／ ／／／ ／／／

$ sudo cp MY_XCODE_BUILD_OUTPUT_DIR/appledoc /usr/local/bin$ mkdir ~/Library/Application\ Support/appledoc$ cp -R appledoc/Templates/ ~/Library/Application\ Support/appledoc

To verify that appledoc have been sucessfully installed you can issue the following command in the Terminal:

$ appledoc --help

If everything is installed correctly the help page for appledoc will be printed to the Terminal window.

Generating the Documentation

In order to generate the documentation we’ll first create a newAggregate targetfor the project called “Documentation”. 

在项目模版中other 有一个aggregate可选

That way the normal build will not be slowed down by generation of the documentation. Additionally anywarnings or errors in the documentation will not cause the main target build to fail. If you want your documentation to automatically be updated every time you build the main target just add the “Documentation” target to the dependencies of the main target.

如果需要自动 更新文档，需要把documentation目标 加入到主项目的依赖中，以完成自动的调用target

在项目的build phases中的target dependenciest的，我们看到的就是要在原来系统的－target dependencies中添加刚建的Documentation。

Next we’ll create a new Script Build Phase and add it to the “Documentation” target. This script will execute the appledoc tool. build the documentation files and install the documentation set into Xcode in one step.

All the appledoc settings are briefly described in the command line help we printed above. A more thorough description of each setting and their implications are available in the online documentation.

The most important ones in terms of Xcode build integration are --logformat xcode and --exit-threshold 2. These will ensure that any warnings or errors are logged in a format compatible with Xcode’s build output.

 Additionally, the build will only be marked as failed if errors are encountered. Undocumented classes or methods will just be flagged with a warning. 此外，如果在build过程中遇到错误，非法的未定义的类或方法会被纪录在警告中。。。。。。 。。。。

The --keep-undocumented-objects and --keep-undocumented-members settings 如果看到这些设置，调整document的产生

ensures that all classes, methods, properties, etc. will be included in the documentation even if they are not explicitly documented. This also have the useful side effect of flagging any missing documentation with a warning in the build output making it easier to spot anything that’s been left out.

Besides parsing the comments and generating documentation files, the appledoc tool will finally install thefinished documentation set into Xcode thus making it available for searching and browsing. 

除了产生标注，产生文档，appledoc工具可以 完成安装，方便在xcode中查找。

Writing the Documentation

So far the generated documentation doesn’t contain more than just an empty framework so the next step is to write it.

The appledoc tool makes it fairly easy to write the documentation since its syntax is based on human readable source code comments. In general appledoc uses a slightly modified version of the standard multiple line and single line comment styles of Objective C with a few extra markups, for example:

/** Query the geonames.org service for the name of the place near the given position (WGS84)   @param latitude The latitude for the position. @param longitude The longitude for the position. */- (void)findNearbyPlaceNameForLatitude:(double)latitude longitude:(double)longitude;

This will displayed in the contextual Xcode Quick Help area like this: build 完成后，我们就可以在Xcode的quick help中看到说明，但是不是在一个document html中？

I will not go deeper into the specific syntax for specifying the contents but the full documentation is available on the appledoc page on GitHub.

Usage: appledoc [OPTIONS] <paths to source dirs or files>  ＝＝＝＝＝＝＝＝＝通过appledoc命令行来产生文档。。。。


PATHS
  -o, --output <path>                     Output path
  -t, --templates <path>                  Template files path
      --docset-install-path <path>        DocSet installation path
  -s, --include <path>                    Include static doc(s) at path
  -i, --ignore <path>                     Ignore given path
  -x, --exclude-output <path>             Exclude given path from output
      --index-desc <path>                 File including main index description


PROJECT INFO
  -p, --project-name <string>             Project name
  -v, --project-version <string>          Project version
  -c, --project-company <string>          Project company
      --company-id <string>               Company UTI (i.e. reverse DNS name)


OUTPUT GENERATION
  -h, --create-html                       [b] Create HTML
  -d, --create-docset                     [b] Create documentation set
  -n, --install-docset                    [b] Install documentation set to Xcode
  -u, --publish-docset                    [b] Prepare DocSet for publishing

      --clean-output                      [b] Remove contents of output path before starting !!CAUTION!!

== === === =====

象Java语言本身就自带javadoc命令，可以从源码中抽取文档。今天抽空调研了一下objective-c语言的类似工具。

从stackoverflow 上找到三个比较popular的工具：doxygen, headdoc和appledoc 。它们分别的官方网址如下：

• docxygen http://www.stack.nl/~dimitri/doxygen/index.html
• headdoc http://developer.apple.com/opensource/tools/headerdoc.html
• appledoc http://gentlebytes.com/appledoc/

appledoc -o ./doc --project-name ynote --project-company youdao .

WARN: --company-id argument or global setting not given, but creating DocSet is enabled, will use 'com.flycent.propertysales'!
WARN | MBRoundProgressView: Comment found in MBProgressHUD.h@351 and MBProgressHUD.m@670!
Oops, something went wrong...

http://gentlebytes.com/appledoc/。。。。 我们可以参考的URL

／／

Xcode integration

You can setup Xcode to handle automatic source code documentation generation for your project. Just add a build script and run appledoc using your desired command line. You can either have it run each time you build or add the script to a separate target to run it manually

url：：：http://gentlebytes.com/appledoc-docs-examples-xcode/

there is special log format suited for Xcode builds:

appledoc--project-name appledoc--project-company "Gentle Bytes"--company-id com.gentlebytes--output ~/help--logformat xcode.

／／

在这个过程中，我们遇到一些问题。

http://www.infinite-loop.dk/blog/2011/06/providing-custom-documentation-in-xcode/