理解python中的文档字符串

  我们在使用def 关键字定义一个函数时，其后必须跟有函数名和包括形式参数的圆括号。函数体的下一行开始，必须是缩进的。函数体的第一行可以是字符串，这个字符串就是文档字符串（documentation string），通常也称作：docstring。

   文档字符串的定义：

         在函数体的第一行，我们可以使用一对三个单引号（'''）或者一对三个双引号（"""）来定义文档字符串，文档字符串通常第一行以大写字母开头，以句号（.）结束，第二行是空行，第三行开始是详细描述。强烈建议，为你重要的寒素写文档字符串都遵循此惯例。

  文档字符串的作用：

      文档字符串是我们使用python过程中一个很重要的工具，他对程序文档很有帮助，使程序很容易理解。甚至当程序运行的时候，我们可以从一个函数中返回文档字符串。把函数当做一个对象来看，这更有助于我们的理解，就相当于获取一个对象的属性（__doc__）.

     有些文档字符串工具可以在线处理或打印文档，或让用户交互的浏览代码;在代码中加入文档字符串是一个好的作法，应该养成这个习惯。

     如果你在Python中已经使用过help()，那么你已经看到如何使用文档字符串了!它所做的仅仅是获取函数的 __doc__ 属性，并以一个整洁的方式显示给你。你可以在上面的函数——在你的程序中仅包括help(printMax)尝试一下。记得按下q键，退出help.

    自动化工具可以从你的程序中以这种方式检索文档。因此，我强烈建议，为你写的任何重要函数使用文档字符串。来自Python的自动化工具pydoc命令使用文档字符串的工作原理类似于help()。

  示例代码：

>>> def printMax(x,y):
...     '''打印两个数中的最大值。
...
...     两个值必须都是在整形数。'''
...     x=int(x)
...     y=int(y)
...     if x>y:
...             print(x,'最大')
...     else:
...             print(y,'最大')
...
>>> printMax(3,5)
(5, '\xd7\xee\xb4\xf3')

>>> help(printMax)
Help on function printMax in module __main__:

printMax(x, y)
    打印两个数中的最大值。

    两个值必须都是在整形数。

>>> print(printMax.__doc__)
打印两个数中的最大值。

        两个值必须都是在整形数。