所有的文档注释应为 Sphinx 可理解的 reStructuredText 格式,其格式根据注释行数而变化。
如果只有一行,闭合的三引号和开头的三引号在同一行,
否则开头的三引号与文本在同一行,而闭合的三引号另起一行:
def foo():
"""This is a simple docstring"""
def bar():
"""This is a longer docstring with so much information in there
that it spans three lines. In this case the closing triple quote
is on its own line.
"""
模块标头包含一个 utf-8 编码声明(即使没有使用非 ASCII 字符,也始终推荐这么做)
和一个标准的文档注释:
# -*- coding: utf-8 -*-
"""
package.module
~~~~~~~~~~~~~~
A brief description goes here.
:copyright: (c) YEAR by AUTHOR.
:license: LICENSE_NAME, see LICENSE_FILE for more details.
"""
请留意,合适的版权和许可证文件对于 Flask 扩展通过审核是必须的。