Python文档化开发注释规范

1.1.1.1.原则在语言要求的地方注释，以标准的注释语法!我们禁止惊奇！一切规范化到谁都可以准确的猜测出正确的结果最好！(就象FreeBSD的组织方式...)注释说明必要的信息，我们不期望精彩的小说在注释中诞生!适当的版本标识尽量使用CVS等版本管理系统自动提供的解析因为如果自个儿来写的话难以统一修改适当的设计思路描述适当的算法设计描述2.2.2.2.文档化标签由于开发语言非常丰富，所以选择了最通用和稳定的文档化工具来支持:DoxyGen是种支持C++,C,Java,Objective-C,IDL(CorbaandMicrosoftflavors)以及PHP,C#andD等等语言的文档化工具.成熟，功能强大,支持广泛甚至于提供了图形界面的管理工具对于所有支持多行注释的语言其实都可以应用epydoc是纯Python实现的Python专用文档化工具与Python结合非常自然，稳定，可扩展2.1.2.1.2.1.2.1.基础标签命令仅仅列举我们推荐使用的文档化标签,,,,进一步的标签命令,,,,请自行进入相关页面学习EpyDocEpyDocEpyDocEpyDoc注释规范DoxyGenDoxyGenDoxyGenDoxyGen注释规范epydocepydocepydocepydoc解析支持的标签规范目录py常用命令py文献信息py状态信息py模块信息py函式信息py提醒信息py关联信息py标签格式py注释风格3.3.3.3.pypypypy常用命令讲述基本的常用标签命令3.1.3.1.3.1.3.1.pypypypy文献信息3.2.3.2.3.2.3.2.pypypypy状态信息3.3.3.3.3.3.3.3.pypypypy模块信息3.4.3.4.3.4.3.4.pypypypy函式信息3.5.3.5.3.5.3.5.pypypypy提醒信息@author:@author:@author:@author:...作者@license:@license:@license:@license:...版权@contact:@contact:@contact:@contact:...联系@version:@version:@version:@version:...版本推荐使用$Id$@todo@todo@todo@todo[ver]:...改进,可以指定针对的版本@var@var@var@varv:...模块变量v说明@type@type@type@typev:...模块变量类型v说明@param@param@param@paramp:...参数p说明@type@type@type@typev:...参数p类型说明@return:@return:@return:@return:...返回值说明@rtype@rtype@rtype@rtypev:...返回值类型说明@note:@note:@note:@note:...注解@attention:@attention:@attention:@attention:...注意@bug:@bug:@bug:@bug:...问题3.6.3.6.3.6.3.6.pypypypy关联信息4.4.4.4.pypypypy标签格式约定文档化标签的语法epydoc支持三种标签的语法！EpytextEpytextEpytextEpytext:@tag:内容...ReStructuredTextReStructuredTextReStructuredTextReStructuredText::tag:内容...JavadocJavadocJavadocJavadoc:@tag内容...为了简化学习，在新浪标准化开发中我们推荐统一使用@tag:内容...格式5.5.5.5.pypypypy注释风格约定文档化标签放置依照Python本身的注释风格自然的进行1#OtTool.py文件(模块)头部2OtterToolsmainscript3@version:$Id$4@author:U{Zoom.Quietmailto:[e-mail]}5@see:参考资料链接等等67importsys,string8classottool:9OtterTools主类10-组织其它小工具，完成任务11@todo:计划完成……1213def__init__(self):14调用相关模块，初始化(当前比较简单，对象初始化时就完成所有任务)15-应用OtCUI参数理解;获得有效变量1617self.cui=OtCUI.otcui()18...__init__.py中的注释成为包文档文件头部注释成为模块文档紧贴class声明后的注释成为类文档紧贴def声明后的注释成为函式文档@warning:@warning:@warning:@warning:...警告@see:@see:@see:@see:...参考资料6.6.6.6.doxdoxdoxdox常用命令讲述基本的常用标签命令6.1.6.1.6.1.6.1.doxdoxdoxdox文献信息6.2.6.2.6.2.6.2.doxdoxdoxdox状态信息6.3.6.3.6.3.6.3.doxdoxdoxdox模块信息6.4.6.4.6.4.6.4.doxdoxdoxdox函式信息6.5.6.5.6.5.6.5.doxdoxdoxdox提醒信息6.6.6.6.6.6.6.6.doxdoxdoxdox关联信息@author@author@author@author...作者@brief@brief@brief@brief...摘要@file@file@file@file...文件声明@version@version@version@version...版本推荐使用$Id$@todo@todo@todo@todo...改进,可以指定针对的版本@var@var@var@var...模块变量说明@typedef@typedef@typedef@typedef...模块变量类型说明@param@param@param@paramp...参数p说明@arg@arg@arg@arg...列表说明参数信息@return@return@return@return...返回值说明@retval@retval@retval@retval...返回值类型说明@note@note@note@note...注解@attention@attention@attention@attention...注意@bug@bug@bug@bug...问题@warning@warning@warning@warning...警告@sa@sa@sa@sa...参考资料7.7.7.7.doxdoxdoxdox标签格式约定文档化标签的语法epydoc支持两种标签的语法！doxygendoxygendoxygendoxygen:\tag内容...JavadocJavadocJavadocJavadoc:@tag内容...为了简化学习，在新浪标准化开发中我们推荐统一使用@tag:内容...格式8.8.8.8.doxdoxdoxdox注释风格约定文档化标签放置依照C/C++JAVA类别语言注释风格自然的进行/***一个示范类，描述在此*/classTest{public:/***一个enum.*详细描述可以多行*/enumTEnum{TVal1,/**单行注释*/}*enumPtr,/**enumpointer.Details.*//***构造器函式*详细描述可以多行*/Test();/***一个普通函式描述和参数等等的叙述*@parama整数参数*@params字串指针参数*@seeTest()参看..*@return返回值描述*/inttestMe(inta,constchar*s);/***纯虚成员函式*@seetestMe()参看*@paramc1第一参数*@paramc2第二参数*/virtualvoidtestMeToo(charc1,charc2)=0;/***一个公共变量*详细描述*/intpublicVar;};DoxyGen支持多种注释声明,仅仅是在标准基础上添加一点儿:JavaDoc样式的:/***...text...*/Qt样式的:/*!...text...*/C++样式的://////...text...///or//!//!...text...//!我们推荐简化的Qt风格/*!引发的多行注释...*/正常結束8.1.8.1.8.1.8.1.输出美化控制可以通过简单的约定来美化文档的输出但是不要深迷于此EpyDocEpyDocEpyDocEpyDoc注释输出控制DoxyGenDoxyGenDoxyGenDoxyGen注释输出控制目录块结构段落列表章节第1章章节1.1第2章引用块行内修饰特殊标签URLs交叉引用警告9.9.9.9.块结构象文章分章节一样注释文本也能定义各种语义区块9.1.9.1.9.1.9.1.段落简单的使用空行就好defexample():这是第一段.段落可以包含多行并可以包含有I{行内修饰}这是第二段.段落间通过空行来区分[...]将生成为:这是第一段.段落可以包含多行并可以包含有行内修饰这是第二段.段落间通过空行来区分9.2.9.2.9.2.9.2.列表象MoinMoin等等结构化文本一样,通过缩进来声明,使用数字或是“-”来引导列表项可以混合defexample():此为段落.1.此为列表项-此为子列表-子列表第二项-此为次层列表,同样可以继续列表下去-只要有一致的缩进2.此为列表第二项可以包含段落和测试引用print'此为测试引用语句'此为测试引用语句此为第二段[...]将生成文档为:此为段落.此为列表项此为子列表子列表第二项此为次层列表,同样可以继续列表下去只要有一致的缩进此为列表第二项可以包含段落和测试引用print'此为测试引用语句'此为测试引用语句此为第二段9.3.9.3.9.3.9.3.章节使用ReStructuredText结构化文本的声明方式defexample():此段不在任何章节中.第1章=========这为第1章中的段落章节1.1-----------此为章节1.1中的段落第2章=========此为第2章中的段落.[...]将生成:此段不在任何章节中.9.3.1.9.3.1.9.3.1.9.3.1.第1111章这为第1章中的段落9.3.1.1.9.3.1.1.9.3.1.1.9.3.1.1.章节1.11.11.11.1此为章节1.1中的段落9.3.2.9.3.2.9.3.2.9.3.2.第2222章此为第2章中的段落.9.4.9.4.9.4.9.4.引用块同样是利用ReStructuredText的引用声明defexample():使用“：：”引出引用块::原文//引用块此为在引用块后的段落还是空行来区分.[...]生成的文档类似:使用“：：”引出引用块:原文//引用块此为在引用块后的段落还是空行来区分.10.10.10.10.行内修饰简单的字体声明defexample():I{B{行内修饰}可以嵌套}在多行内.-I{斜体}-B{加重}-C{源代码}C{my_dict={1:2,3:4}}.[...]将生成类似文档:行内修饰可以嵌套在多行内.斜体加重'源代码切换行号显示lang=enid=CA-a2c6d35298ec49bd0ec78225786ef69c7c95a12b_000dir=ltr1my_dict={1:2,3:4}10.1.10.1.10.1.10.1.特殊标签10.1.1.10.1.1.10.1.1.10.1.1.URLsURLsURLsURLsdefexample():-U{}-U{}-U{Theepydochomepage}-U{TheB{I{Python}}homepag