python系列教程169——__doc__

Posted 2022-04-20 人工智能AI技术

朋友们，如需转载请标明出处：https://blog.csdn.net/jiangjunshow

声明：在人工智能技术教学期间，不少学生向我提一些python相关的问题，所以为了让同学们掌握更多扩展知识更好地理解AI技术，我让助理负责分享这套python系列教程，希望能帮到大家！由于这套python教程不是由我所写，所以不如我的AI技术教学风趣幽默，学起来比较枯燥；但它的知识点还是讲到位的了，也值得阅读！想要学习AI技术的同学可以点击跳转到我的教学网站。PS：看不懂本篇文章的同学请先看前面的文章，循序渐进每天学一点就不会觉得难了！

除了#注释外，Python也支持可自动附加在对象上的文档，而且在运行时还可保存查看。从语法上来说，这类注释是写成字符串，放在模块文件、函数以及类语句的顶端。Python会自动封装这个字符串，也就是成为所谓的文档字符串，使其成为相应对象的__doc__属性。

例如，拿下面的文件docstrings.py举例。其文档字符串出现在文件开端以及其中的函数和类的开头。在这里，文件和函数多行注释使用的是三重引号块字符串。

"""

Module documentation

Words Go Here

"""

spam = 40




def square（x）:

    """

    function documentation

    can we have your liver then?

    """

    return x ** 2           # square




class Employee:

    "class documentation"

    pass




print（square（4））

print（square.__doc__）

注释会保存在__doc__属性中以供查看。因此，要显示这个模块以及其对象关联的文档字符串，我们只需要导入这个文件，简单的打印其__doc__属性即可：

>>>import docstrings

16

   function documentation

   can we have your liver then?




>>>print（docstrings.__doc__）




Module documentation

Words Go Here




>>>print（docstrings.square.__doc__）

   function documentation

   can we have your liver then?




>>>print（docstrings.Employee.__doc__）

   class documentation

要取出模块中类的方法函数的文档字符串，可以通过这种语法：module.class.method.doc。

文档字符串的文字应该有什么内容，并没有什么标准（不过有些公司有内部标准）。现在已经有各种标记语言和模板协议（例如，html或XML），但是，似乎没有在Python世界中流行起来。然而，要说服程序员使用手动编写HTML为代码编写文档，那是不可能的！通常来说，文档在程序员之间的优先级都偏低。如果你看到文件中有任何注释，那都已经算是幸运了。不过，强烈建议你详细的为代码编写文档，这其实是写好代码的重要部分。

要查看内置模块的可读的说明时，可将其导入，并打印其__doc__字符串。

>>>import sys

>>>print（sys.__doc__）

This module provides access to some objects used or maintained by the

interpreter and to functions that interact strongly with the interpreter.




Dynamic objects:




argv -- command line arguments; argv[0] is the script pathname if known

path -- module search path; path[0] is the script directory,else ''

modules -- dictionary of loaded modules

...more text omitted...

内置模块内的函数、类以及方法在其__doc__属性内也有附加的说明信息。

>>>print（sys.getrefcount.__doc__）

getrefcount（object） -> integer




Return the reference count of object.The count returned is generally

one higher than you might expect,because it includes the （temporary）

...more text omitted...