全网最适合入门的面向对象编程教程：35 Python的内置数据类型-文档字符串和__doc__属性

全网最适合入门的面向对象编程教程：35 Python 的内置数据类型-文档字符串和__doc__属性

摘要：

在 Python 中，文档字符串（Docstring）是一种用于为模块、类、方法或函数编写文档的字符串，通常放置在定义的开头，紧跟在声明之后。文档字符串使用三重引号（""" 或 '''）包围，可以跨越多行。

原文链接：

FreakStudio的博客

往期推荐：

学嵌入式的你，还不会面向对象？？！

全网最适合入门的面向对象编程教程：00 面向对象设计方法导论

全网最适合入门的面向对象编程教程：01 面向对象编程的基本概念

全网最适合入门的面向对象编程教程：02 类和对象的 Python 实现-使用 Python 创建类

全网最适合入门的面向对象编程教程：03 类和对象的 Python 实现-为自定义类添加属性

全网最适合入门的面向对象编程教程：04 类和对象的Python实现-为自定义类添加方法

全网最适合入门的面向对象编程教程：05 类和对象的Python实现-PyCharm代码标签

全网最适合入门的面向对象编程教程：06 类和对象的Python实现-自定义类的数据封装

全网最适合入门的面向对象编程教程：07 类和对象的Python实现-类型注解

全网最适合入门的面向对象编程教程：08 类和对象的Python实现-@property装饰器

全网最适合入门的面向对象编程教程：09 类和对象的Python实现-类之间的关系

全网最适合入门的面向对象编程教程：10 类和对象的Python实现-类的继承和里氏替换原则

全网最适合入门的面向对象编程教程：11 类和对象的Python实现-子类调用父类方法

全网最适合入门的面向对象编程教程：12 类和对象的Python实现-Python使用logging模块输出程序运行日志

全网最适合入门的面向对象编程教程：13 类和对象的Python实现-可视化阅读代码神器Sourcetrail的安装使用

全网最适合入门的面向对象编程教程：全网最适合入门的面向对象编程教程：14 类和对象的Python实现-类的静态方法和类方法

全网最适合入门的面向对象编程教程：15 类和对象的 Python 实现-__slots__魔法方法

全网最适合入门的面向对象编程教程：16 类和对象的Python实现-多态、方法重写与开闭原则

全网最适合入门的面向对象编程教程：17 类和对象的Python实现-鸭子类型与“file-like object“

全网最适合入门的面向对象编程教程：18 类和对象的Python实现-多重继承与PyQtGraph串口数据绘制曲线图

全网最适合入门的面向对象编程教程：19 类和对象的 Python 实现-使用 PyCharm 自动生成文件注释和函数注释

全网最适合入门的面向对象编程教程：20 类和对象的Python实现-组合关系的实现与CSV文件保存

全网最适合入门的面向对象编程教程：21 类和对象的Python实现-多文件的组织：模块module和包package

全网最适合入门的面向对象编程教程：22 类和对象的Python实现-异常和语法错误

全网最适合入门的面向对象编程教程：23 类和对象的Python实现-抛出异常

全网最适合入门的面向对象编程教程：24 类和对象的Python实现-异常的捕获与处理

全网最适合入门的面向对象编程教程：25 类和对象的Python实现-Python判断输入数据类型

全网最适合入门的面向对象编程教程：26 类和对象的Python实现-上下文管理器和with语句

全网最适合入门的面向对象编程教程：27 类和对象的Python实现-Python中异常层级与自定义异常类的实现

全网最适合入门的面向对象编程教程：28 类和对象的Python实现-Python编程原则、哲学和规范大汇总

全网最适合入门的面向对象编程教程：29 类和对象的Python实现-断言与防御性编程和help函数的使用

全网最适合入门的面向对象编程教程：30 Python的内置数据类型-object根类

全网最适合入门的面向对象编程教程：31 Python的内置数据类型-对象Object和类型Type

全网最适合入门的面向对象编程教程：32 Python的内置数据类型-类Class和实例Instance

全网最适合入门的面向对象编程教程：33 Python的内置数据类型-对象Object和类型Type的关系

全网最适合入门的面向对象编程教程：34 Python的内置数据类型-Python常用复合数据类型：元组和命名元组

更多精彩内容可看：

给你的 Python 加加速：一文速通 Python 并行计算

一文搞懂 CM3 单片机调试原理

肝了半个月，嵌入式技术栈大汇总出炉

电子计算机类比赛的“武林秘籍”

一个MicroPython的开源项目集锦：awesome-micropython，包含各个方面的Micropython工具库

文档和代码获取：

可访问如下链接进行对文档下载：

https://github.com/leezisheng/Doc

本文档主要介绍如何使用 Python 进行面向对象编程，需要读者对 Python 语法和单片机开发具有基本了解。相比其他讲解 Python 面向对象编程的博客或书籍而言，本文档更加详细、侧重于嵌入式上位机应用，以上位机和下位机的常见串口数据收发、数据处理、动态图绘制等为应用实例，同时使用 Sourcetrail 代码软件对代码进行可视化阅读便于读者理解。

相关示例代码获取链接如下：https://github.com/leezisheng/Python-OOP-Demo

正文

在 Python 中，我们可以为方法、类和模块添加文档字符串，这些文档字符串可以通过一个特殊属性__doc__获取。文档字符串（docstring）是一种用于描述类、函数、模块或方法的字符串，通常位于定义的顶部，并用于提供有关其功能和用法的信息。文档字符串通常被包含在三引号（''' 或 """）中，并位于类、函数、模块或方法定义的顶部。

例如，在下列示例中，我们为 MasterClass 主机类及其 StartMaster 开启主机方法添加必要注释，并通过以下语句访问：

_# 访问MasterClass类的__doc__属性_
    print(MasterClass.__doc__)
    _# 访问MasterClass类中StartMaster方法的__doc__属性_
    print(MasterClass.StartMaster.__doc__)

示例代码如下：

class MasterClass(SerialClass,PlotClass):
    '''
    MasterClass：该类表示主机类，主要用于接收传感器数据、收发指令等

    具有如下属性：
        state       —— 表示主机工作状态
        port        —— 表示主机端口号
        wintitle    —— 表示窗口标题
        ... ...

    具有如下方法：
        StartMaster     —— 开启主机
        StopMaster      —— 停止主机
        RecvSensorValue —— 接收传感器数据值
        ... ...
    '''
    ...
    _# 类的初始化_
    def __init__(self,state:int = IDLE_STATE,port:str = "COM17",wintitle:str="Basic plotting examples",plottitle:str="Updating plot",width:int=1000,height:int=600):
        pass
    _# 开启主机_
    def StartMaster(self):
        '''
            StartMaster方法——开启主机
            调用SerialClass.OpenSerial()方法
        :return: 无返回值
        '''
        pass

如下为运行结果：

同时，我们也可以给命名元组添加文档字符串。使用一个类继承对应的命名元组，并在类中添加文档注释，示例代码如下：

from collections import namedtuple

_Sensor = namedtuple("Sensor","ID CURRENTVALUE MAXVALUE MINVALUE")

class Sensor(_Sensor):
    '''
        这是一个继承自表示传感器数据的命名元组的类
        具有四个属性：
            （1） ID              ： 表示传感器ID号
            （2） CURRENTVALUE    ： 传感器采集到的当前数据值
            （3） MAXVALUE        ： 传感器采集到的最大数据值
            （4） MINVALUE        ： 传感器采集到的最小数据值
    '''
sensor_tuple=Sensor(ID="16",CURRENTVALUE=32,MAXVALUE=62,MINVALUE=2)
print(sensor_tuple.__doc__)

运行结果如下：