写在前面

如果说高效率的算法是一个项目的内核，那么完备的文档注释、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):"""summaryNothingArgs:a (str): hhhhb (int): bbbbReturns:str: nono"""

使用 pycharm 查看如下：

Numpy

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

def test_numpy(a, b):"""summaryAAAParameters----------a : strinputb : intinputReturns-------c : strnono"""

在pycharm中显示如下：

reStructuredText

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

def test_reStructuredText(a: str):"""summaryTest 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博客