注释形式
# 语法上，Python注释只有单行注释 # 注释内容
# 习惯上Python使用三引号作为多行注释，但三引号本质上是字符串
def func1():
"""多行注释"""
def f2():
# 单行注释
# IndentationError: expected an indented block after function definition on line 1
注释风格
reStructuredText
# reStructuredText
"""
reStructuredText
:param x:
:param y:
:return:
"""
代码片段节选自SQLAlchemy
class Engine(
ConnectionEventsTarget, log.Identified, inspection.Inspectable["Inspector"]
):
"""
Connects a :class:`~sqlalchemy.pool.Pool` and
:class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
source of database connectivity and behavior.
An :class:`_engine.Engine` object is instantiated publicly using the
:func:`~sqlalchemy.create_engine` function.
.. seealso::
:doc:`/core/engines`
:ref:`connections_toplevel`
"""
Connects a :class:`~sqlalchemy.pool.Pool` and
:class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a
source of database connectivity and behavior.
An :class:`_engine.Engine` object is instantiated publicly using the
:func:`~sqlalchemy.create_engine` function.
.. seealso::
:doc:`/core/engines`
:ref:`connections_toplevel`
reStructuredText格式，用于编写文档的轻量级标记语言，常用于Python文档、Sphinx文档生成工具等。:class:表示后面跟着的是一个类名，而.Session则表示当前模块下的Session类。写法优点，一是明确指示某个类或者对象的引用，文档清晰易读，二是使用 Sphinx 等工具生成文档时，可以自动解析和格式化生成文档。
Epytext
# Epytext
"""
Epytext
@param x:
@param y:
@return:
"""
Numpy
# Numpy
"""
Numpy
Parameters
----------
x
y
Returns
-------
"""
# Google
"""
Google
Args:
x:
y:
Returns:
"""
PyCharm 设置函数注释风格
# Python设置函数注释
# Preferences/Settings >> Tools >> Python Integrated Tools >> Doctrings