Table of Contents

• • 注释风格
    • reStructuredText（PyCharm默认）
    • NumPy
    • Google（官方推荐）
    • 比较
    • 参考文献
    • 智能提示

注释风格

reStructuredText（PyCharm默认）

reStructuredText（PyCharm默认）

def func(path, field_storage, temporary):
    '''基本描述

    详细描述

    :param path: The path of the file to wrap
    :type path: str
    :param field_storage: The :class:`FileStorage` instance to wrap
    :type field_storage: FileStorage
    :param temporary: Whether or not to delete the file when the File instance is destructed
    :type temporary: bool
    :returns: A buffered writable file descriptor
    :rtype: BufferedFileStorage
    '''
    pass

NumPy

NumPy Style

def func(path, field_storage, temporary):
    '''基本描述

    详细描述

    Parameters
    ----------
    path : str
        The path of the file to wrap
    field_storage : FileStorage
        The :class:`FileStorage` instance to wrap
    temporary : bool
        Whether or not to delete the file when the File instance is destructed

    Returns
    -------
    BufferedFileStorage
        A buffered writable file descriptor
    '''
    pass

Google（官方推荐）

Google Style

def func(path, field_storage, temporary):
    '''基本描述

    详细描述

    Args:
        path (str): The path of the file to wrap
        field_storage (FileStorage): The :class:`FileStorage` instance to wrap
        temporary (bool): Whether or not to delete the file when the File instance is destructed

    Returns:
        BufferedFileStorage: A buffered writable file descriptor
    '''
    pass

比较

中文版：https://www.osgeo.cn/sphinx/usage/extensions/napoleon.html
英文版：https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

参考文献

Python风格规范 — Google 开源项目风格指南
Sphinx入门——快速生成Python文档
Sphinx是Python文档生成器

智能提示

1. 类型注解 方式1

from PIL import Image
im = Image.open('Me.jpg') # type: Image.Image

2. 类型注解 方式2

from PIL import Image
im = Image.open('Me.jpg')
""":type: Image.Image"""

3. 使用isinstance指定

from PIL import Image
im = Image.open('Me.jpg')
assert isinstance(im, Image.Image)