理解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__)
     
     
    
    

    
    

     
     

    
    
    
    

     
     

      
      打印两个数中的最大值。
     
     
    
    

    
    

     
     

    
    
    
    

     
     
 
     
     
    
    

    
    

     
     

    
    
    
    

     
     

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