文档字符串的作用（文档字符串）

5.5 文档字符串

开发者在编写函数或模块时不光要自己能看懂    
    
    
，在和他人合作共同开发或者被他人调用时也需要他人也能看懂 
    
    
  。这个时候就可以为自己编写的函数 
    
    
  、模块或者类添加相应的文档字符串(docstring)进行说明了
     


     


     
。

一般的  


     


     


  ，如果想要在模块中添加模块文档字符串


 




 




 
，则需要在模块的最上方用3个双引号引住内容   

   

   

，这部分内容则自动会被识别为模块的文档字符串 




 




 




。

注意：模块文档字符串上方可以有注释内容   

     

     

 ，但是不能有任何Python语句



  




  




  ，否则不会被识别成模块文档字符串 

   

   

 。

同理  


  


  


，如果想要在函数中添加文档字符串    
     
     
，也是需要在定义函数后马上跟上函数文档字符串内容
     

     

     。否则也不会被识别成函数文档字符串  




  




  




。在以后类的定义时也是同理 


  


  


。

放在函数开头的字符串称为函数文档字符串(docstring)




   




   




   ，将作为函数的一部分存储起来
     
     
     。下面的代码演示了如何给函数添加文档字符串： def square(x): Calculates the square of the number x. return x * x

可以像下面这样访问文档字符串：

>>> square.doc

Calculates the square of the number x.

注意__doc__是函数的一个属性   




   




   



。属性名中的双下划线表示这是一个特殊的属性 



 



 



。

示例：为函数添加文档字符串并对参数进行说明 def frb_num_to_str(p_num, p_is_makeup=False, p_int_num=6): """ 将一个int类型或者float类型转变成str类型              。若p_is_makeup为True 



 



 


，则需要补齐为p_int_num位
    




    




    


。 @param p_num: 输入的参数               ，一个int类型或者float类型数据 @param p_is_makeup: 是否要补齐到指定位数 @param p_int_num: 补齐的指定位数 @return: """ result = p_num if isinstance(p_num, int): result = str(p_num) elif isinstance(p_num, float): result = str(p_num)[:str(p_num).find(.)] elif isinstance(p_num, str): result = p_num # 判断传入的num的类型 if p_is_makeup and len(result) < p_int_num: result = 0 * (p_int_num - len(result)) + result return result

提示：

为函数
     


     


     
、类 




 




 




、模块自动添加文档字符串参照Pycharm软件设置














。