":","@"与python docstrings中没有任何区别

Question

我只是想更好地感受Python文档字符串的布局(之间""" """)

我见过不同布局的docstrings ......比如...

"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

这些都有功能吗？是@用药剂关联？或者这些只是开发者之间的偏好？我查看了docstrings的样式指南,但看不到它在哪里解决这些问题......

谢谢!

Answer 1

格式

Python文档字符串可以按照几种格式编写:

- Javadoc

从历史上看,javadoc风格很普遍.它被用来通过epydoc的(与被叫Epytext格式)生成文档.

例:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- reST

如今,可能更普遍的格式是sphinx用于生成文档的reStructuredText(reST)格式.

例:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- 谷歌

谷歌有自己的格式,很常用.它也可以由Sphinx解释.请注意,Numpy建议您遵循自己的基于Google格式的numpydoc,并由Sphinx使用.

例:

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

转换/生成

可以使用像Pyment这样的工具自动生成尚未记录的Python项目的文档字符串,或者将现有文档字符串(可以混合多种格式)从格式转换为另一种格式.

注意:这些示例来自Pyment文档.你可以看到这个tuto有关docstrings的更多信息.