首先是转载内容:
一、自动生成注释代码
添加一个快捷键,生成 注释代码
ThisService 下载连接:http://wafflesoftware.net/thisservice/
Doxygen.rb 下载连接:http://www.brokenrul.es/blog/wp-content/uploads/2011/03/Doxygen.rb_.zip
1、打开ThisService,进行以下配置
Name:右键菜单中的名字
Script:将Doxygen.rb拖拽到这里
2、打开系统偏好设置,找到键盘,进行以下配置
这里我将快速文档注释的快捷键设置成了Command + option + /
3、使用
选中需要注释的函数名,包括所有的参数,右键点击快速文档注释,或者直接按快捷键即可。
二、生成文档
生成文档有三种方式:
docxygen http://www.stack.nl/~dimitri/doxygen/index.html
headdoc http://developer.apple.com/opensource/tools/headerdoc.html
appledoc http://gentlebytes.com/appledoc/
docxygen 感觉是这3个工具中支持语言最多的,可以配置的地方也比较多。我大概看了一下文档,觉得还是比较复杂,而且默认生成的风格与苹果的风格不一致。就去看后面 2个工具的介绍了。另外,它虽然是开源软件,但是没有将源码放到github上让我感觉这个工具的开发活跃度是不是不够。
headerdoc
headerdoc 是xcode 自带的文档生成工具。在安装完xcode后,就可以用命令行:headdoc2html + 源文件名 来生成对应的文档。我个人试用了一下,还是比较方便的,不过headerdoc的注释生成规则比较特别,只生成以 /! / 的格式的注释。还有一个缺点是每个类文件对应一个注释文件,没有汇总的文件,这点感觉有点不爽。
appledoc
appledoc是在stackoverflow上被大家推荐的一个注释工具。有几个原因造成我比较喜欢它:
它默认生成的文档风格和苹果的官方文档是一致的,而doxygen需要另外配置。
appledoc就是用objective-c生成的,必要的时候调试和改动也比较方便。
可以生成docset,并且集成到xcode中。这一点是很赞的,相当于在源码中按住option再单击就可以调出相应方法的帮助。
appledoc源码在github上,而doxygen在svn上。我个人比较偏激地认为比较活跃的开源项目都应该在github上。
相对于headerdoc,它没有特殊的注释要求,可以用/* / 的格式,也可以兼容/! /的格式的注释,并且生成的注释有汇总页面。
安装
那么简单介绍一下如何安装appledoc,安装非常简单,只需要2步:
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
使用
使用appledoc时,只需要用如下命令即可:
appledoc -o ./doc --project-name ynote --project-company youdao .
appledoc会扫描当前路径下的所有文件,然后生成好文档放到doc目录下。你也可以用appledoc –help查看所有可用的参数。
基本上使用起来还是比较方便的,详细的信息可以查看官方的文档:http://gentlebytes.com/appledoc/
Posted by 唐巧 Feb 1st, 2012 iOS, xcode
原创文章,版权声明:自由转载-非商用-非衍生-保持署名 | Creative Commons BY-NC-ND 3.0
文章转载自:http://blog.163.com/l1_jun/blog/static/1438638820131126101948669/
================我是分割线========================
aapledoc 参数使用说明
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 --html-anchors <string> [*] The html anchor format to use in DocSet HTML. --clean-output [b] Remove contents of output path before starting !!CAUTION!!
OPTIONS
--keep-intermediate-files [b] Keep intermediate files in output path --keep-undocumented-objects [b] Keep undocumented objects --keep-undocumented-members [b] Keep undocumented members --search-undocumented-doc [b] Search undocumented members documentation --repeat-first-par [b] Repeat first paragraph in member documentation --preprocess-headerdoc [b] Preprocess header doc comments - 10.7 only! --print-information-block-titles [b] Print title of information blocks. "Note:", "Warning:", etc. --use-single-star [b] Use single star for bold marker --merge-categories [b] Merge categories to classes --merge-category-comment [b] Merge category comment to class --keep-merged-sections [b] Keep merged categories sections --prefix-merged-sections [b] Prefix merged sections with category name --explicit-crossref [b] Shortcut for explicit default cross ref template --use-code-order [b] Order sections by the order specified in the input files --crossref-format <string> Cross reference template regex --exit-threshold <number> Exit code threshold below which 0 is returned --docs-section-title <string> Title of the documentation section (defaults to "Programming Guides"
WARNINGS
--warn-missing-output-path [b] Warn if output path is not given --warn-missing-company-id [b] Warn if company ID is not given --warn-undocumented-object [b] Warn on undocumented object --warn-undocumented-member [b] Warn on undocumented member --warn-empty-description [b] Warn on empty description block --warn-unknown-directive [b] Warn on unknown directive or format --warn-invalid-crossref [b] Warn on invalid cross reference --warn-missing-arg [b] Warn on missing method argument documentation --warn-unsupported-typedef-enum [b] Warn on unsupported typedef enum
DOCUMENTATION SET INFO
--docset-bundle-id <string> [*] DocSet bundle identifier --docset-bundle-name <string> [*] DocSet bundle name --docset-desc <string> [*] DocSet description --docset-copyright <string> [*] DocSet copyright message --docset-feed-name <string> [*] DocSet feed name --docset-feed-url <string> [*] DocSet feed URL --docset-feed-formats <values> DocSet feed formats. Separated by a comma [atom,xml] --docset-package-url <string> [*] DocSet package (.xar) URL --docset-fallback-url <string> [*] DocSet fallback URL --docset-publisher-id <string> [*] DocSet publisher identifier --docset-publisher-name <string> [*] DocSet publisher name --docset-min-xcode-version <string> [*] DocSet min. Xcode version --docset-platform-family <string> [*] DocSet platform familiy --docset-cert-issuer <string> [*] DocSet certificate issuer --docset-cert-signer <string> [*] DocSet certificate signer --docset-bundle-filename <string> [*] DocSet bundle filename --docset-atom-filename <string> [*] DocSet atom feed filename --docset-xml-filename <string> [*] DocSet xml feed filename --docset-package-filename <string> [*] DocSet package (.xar,.tgz) filename. Leave off the extension. This will be added depending on the generated package.
MISCELLANEOUS
--logformat <number> Log format [0-3] --verbose <value> Log verbosity level [0-6,xcode] --version Display version and exit --help Display this help and exit
================================================================== [b] boolean parameter, uses no value, use --no- prefix to negate.
[*] indicates parameters accepting placeholder strings:
- %PROJECT replaced with --project-name - %PROJECTID replaced with normalized --project-name - %VERSION replaced with --project-version - %VERSIONID replaced with normalized --project-version - %COMPANY replaced with --project-company - %COMPANYID replaced with --company-id - %YEAR replaced with current year (format yyyy) - %UPDATEDATE replaced with current date (format yyyy-MM-dd) - %DOCSETBUNDLEFILENAME replaced with --docset-bundle-filename - %DOCSETATOMFILENAME replaced with --docset-atom-filename - %DOCSETPACKAGEFILENAME replaced with --docset-package-filename
================================================================== Find more help and tips online:
- http://appledoc.gentlebytes.com/ - http://tomaz.github.com/appledoc/
================================================================== appledoc uses the following open source components, fully or partially:
- DDCli by Dave Dribin - CocoaLumberjack by Robbie Hanson - ParseKit by Todd Ditchendorf - RegexKitLite by John Engelhart - GRMustache by Gwendal Roué - Discount by David Parsons - Timing functions from Apple examples
在实际使用过程中,发现有些注释是必须要写的。
PS.上面说的自动生成注释的工具没成功,所以只能手动写注释了~~~
写了一个小脚本用来调用appledoc快速生成文档,放在了git上。里面有使用说明以及注释示例。
git地址:https://github.com/showhilllee/appledoc
转载请注明出处:http://blog.csdn.net/showhilllee/article/details/47685989