文档化开发注释规范 TableOfContents
原则
- 在语言要求的地方注释，以标准的注释语法!
我们禁止惊奇！一切规范化到谁都可以准确的猜测出正确的结果最好！(就象 FreeBSD 的组织方式...)
- 注释说明必要的信息，我们不期望精彩的小说在注释中诞生!
- 适当的版本标识
- 尽量使用CVS等版本管理系统自动提供的解析
- 因为如果自个儿来写的话难以统一修改
常用的CVS关键字对照表 -- CvsKeywordsList
- 适当的设计思路描述
- 适当的算法设计描述
- 适当的版本标识
文档化标签
- 由于新浪的产品非常丰富，涉及的开发语言也多种多样，所以选择了最通用和稳定的文档化工具来支持:
http://www.stack.nl/~dimitri/doxygen/images/doxygen.png
DoxyGen 是种支持 C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及 PHP, C# and D 等等语言的文档化工具.
- 成熟，功能强大,支持广泛
- 甚至于提供了图形界面的管理工具
- 对于所有支持多行注释的语言其实都可以应用
[http://epydoc.sourceforge.net/ epydoc]
- 是纯Python 实现的 Python 专用文档化工具
- 与Python 结合非常自然，稳定，可扩展
基础标签命令
仅仅列举我们推荐使用的文档化标签,进一步的标签命令,请自行进入相关页面学习
输出美化控制
- 可以通过简单的约定来美化文档的输出
- 但是不要深迷于此
反馈
- 请汇集自个儿的使用体验