代码与API文档

从代码中直接提出API文档, 是一件令人高兴的事. 自己辛苦写的代码, 终于有了给人看得懂的文档了(虽然代码是ugly的)
python还方面的工具也很多的. epydoc就是送的一个小工具(我也不知道什么时候被安装入系统的).

从代码里取出API文档, 是原于一个叫documentation strings的东西. 在python里, 有这种东西的对象如下:
1. modules
2 functions
3 classes
4 methods

在哪里定义docstrings呢?

An object's docsting is defined by including a string constant as the first
statement in the object's definition.

看来, 第一个有效的语句, 并且是string型的, 就是叫docstring
function, classes, method比较好理解, 下面两个特殊一点的对象:
1. 在module中, 在py文件的除了"#"开始的行外, 第一个字符串语句
2. 在package中, docstring在于__init__.py文件中, 情况与module相同

docstring只是第一步. 需要进一步细分文档内容, 比如, 描述一个function的用途, 参数和返回情况. 这时需要在docstring中使用一种叫fields的东西, 如下URL:
* http://epydoc.sourceforge.net/manual-fields.html

如果想对docstring样式控制的话, 还有此功能的:
* http://epydoc.sourceforge.net/manual-epytext.html

BTW: docstring里样式控制就太花了. 加点缩进还是可以忍受的