python 代码注释

写在前面

如果说高效率的算法是一个项目的内核，那么完备的文档注释、API 接口则是项目的外壳，直接与客户交互。
pycharm 提供了 5 种 代码注释格式。
分别是 plain, epytext, google, numpy, reStructuredText

使用方法

在 file / setting / tools / python integrated tools / docstrings

使用 ctrl+q 可以查看某函数的注释

plain

这种模式适合简单的注释，不涉及参数、返回值之类的，简单的几句话即可

def test_plain(a: str, b: int):
    """
    Nothing
    """

Epytext

这种格式源自 java 语言，官方文档。
该格式是一种轻量级的注释方法，使用简单，适合较小的文档，但通用性较差。

代码样式：

def test_epytext(a: str, b: int):
    """
    AAA

    @param a: AA
    @type a: str
    @param b: BB
    @return: CC
    @rtype: str
    """

其中@后的注释块被叫做 filed，不同的 filed 有着不同的含义
下表是 部分官方介绍

上述代码段，在 pycharm 中查看如下：

Google

这是一款使用较广泛的格式，示例代码如下：

def test_google(a: str, b: int):
    """summary

    Nothing

    Args:
        a (str): hhhh
        b (int): bbbb

    Returns:
        str: nono

    """

使用 pycharm 查看如下：

Numpy

这也是一款使用广泛的格式，如下：

def test_numpy(a, b):
    """summary

    AAA

    Parameters
    ----------
    a : str
        input
    b : int
        input

    Returns
    -------
    c : str
        nono

    """

在pycharm中显示如下：

reStructuredText

这款格式适配 sphinx 等网页文档较好，是 pycharm 默认的格式。（但我个人感觉可读性较差）
示例代码：

def test_reStructuredText(a: str):
    """summary
    
    Test hhhh

    :param a: para
    :type a: str
    :return: Nothing
    :rtype: str
    """

pycharm 中查看渲染：

相关程序包

sphinx 是一款自动化生成 python 文档的程序，官方网站, 中文教程推荐
sphinx 基于 reStructuredText 格式，但也支持 google 和 numpy，不支持其他两款。
pyment 是一个命令行程序包，能够相互转化不同格式的注释，文档.

其他

所有的 docstring 使用空行来区分注释块，比如 numpy 格式中，summary 和具体说明中有空行。具体说明和下面的 parameter 间有空行。没有空行会影响注释块的识别。

本文参考了 一个github gist, 一个csdn博客