python doc 简要介绍

Java有Javadoc可以方便的生成帮助文档。python 有pydoc，只要源文件按照docstring的标准（PEP 257）来写，就可以很方便的生成帮助文件。

http://www.python.org/dev/peps/pep-0257/

下面简单的就PEP 257来说明一下

什么是docstring？docstring 就是出现在模块，方法，类后面的第一句声明，这句声明会默认成为，该对象的__doc__变量的内容。

所有的模块（module)通常有docstring，模块中对外引用的函数和类也需要有docstring，公共函数（包括__init__构造器）也应该有DocString，如果是包，可以在包的根目录中的__init__.py文件中写这个模块(module）的DocString。

其他位置书写的文本可能不会做为文档被识别，但是可能被其他的工具识别。

为了保持一致性，使用三引号将 DocString包含，例如："""triple double quotes"""，包含转义字符（'\'）的DocString需要使用转移字符串 r"""raw triple double quotes"""，对于unicode的DocString，使用 u"""Unicode triple-quoted strings""".

DocString有两种形式，单行和多行。

对于单行的DocString需要注意下面几点：

• 即便是简短的单行字符也要用三引号的方式，不能使用 '#' 注释，方便以后单行注释扩展后变成多行
• 包含注释的前后三引号要在同一行，这样看起来更整洁
• 在单行DocString的前后都不要有空行
• 单行DocString不应该是函数或者方法字面表述的另一种翻译。

多行DocString

• 多行注释包括一个概要行，像单行DocString一样，第一行后面是一个空行，然后跟上更详细的描述。将概要行限制在一行，并且后面跟上一个空白行是严格要求的，概要行时候和多行DocString的其实三引号是否在一行不做限制。
• 对于class的DocString，在其前后各加一行空白行。通常来说，class中的方法都是用一个空白行来做分隔的，DocString和第一个方法间要有一个空白，为了美观，在class的定义行和DocString之间要有一个空白行，方法的DocString不需要这么做，除非方法体被空行隔成了几个段，这种情况下，DocString可以看做是一个单独的段落，这时候需要一个空行。、
• 对于命令行的脚本，脚本的使用法放需要和 help 说明一致。帮助文档需要对使用方法有详尽的说明，用户通过帮助可以正确的使用命令，高级用户可以快速的参考所有的选项和说明
• 方法和函数的DocString应该说明他的行为和参数，返回值，功能，以上和限制。可选参数应该被说明。关键字参数是否是interface的一部分。
• class的DocString应该说明类的行为，列出来所有的公共方法，instance变量。如果class会被集成并且有一个interface会在subclass中实现，这个interface应该在docString中单独类出来，class的构造器的docSting应该写在__init__方法中，单独的方法需要有自己的docString
• 如果一个class继承自另外一个class，并且它的行为大部分继承自父类，它的docString应该提到这点并且说明不同之处。使用"override"表示被子类复写的方法说明该类没有调用父类的定义。使用“extend”表示子类是调用的父类的方法。