Effective Python 读书笔记: 第49条: 为每个函数、类和模块编写文档字符串

# -*- encoding: utf-8 -*-

import os

'''
第49条: 为每个函数、类和模块编写文档字符串

关键:
1 docstring
含义: def语句之后，可以提供docstring，将卡法文档与函数关联
形式: """Return""", 注意 """之后接的单词之间没有空格 
用法: result = repr(palindrome.__doc__)
函数的__doc__即会返回最终的函数的文档字符串

2 Sphinx
文档生成工具。可以将纯文本转换为HTML格式

3 为模块编写文档
模块有顶级的docstring.作为源文件的第一条语句。
用三重双引号把它括起来。
docstring的第一行: 描述模块的用途，下面的内容则包含细节。
顶行下面空一行，写详细内容。顶行和三重引号之间没有空格
用法:
"""My First Module.

It is used to tell you how to
write docstring of module.

"""

4 为类编写文档
头一行表示类的作用，空一行，后面的内容表示细节

class Student(object):
    """It means student class.
    
    It includes insert/delete/edit/retrieve
    methods.
    
    """

5 为函数编写文档
第一行表示函数功能，空一行，后面内容表示细节。
样例:
def process(data):
    """It is used to rocess data.
    
    The stepes of processing data are as below:
    Firstly, filter invalid data.
    """
    
6 总结
用docstring为模块，类，方法写文档字符串，
三重引号后无空格，接第一行表示用途，
然后空一行，后面内容表示细节。

参考:
Effectiv Python 编写高质量Python代码的59个有效方法
'''

def palindrome(word):
    """Return True if the given word is a palindrome"""
    return word == word[::-1]


def process():
    result = repr(palindrome.__doc__)
    print result
    print type(result)


if __name__ == "__main__":
    process()