我只是想更好地了解Python文档字符串的布局（在""" """之间）
我见过不同布局的文档字符串......例如......
"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign
:DESCRIPTION:
Tags with colons
DESCRIPTION
And tags with nothing
"""
这些都有功能吗？ @与Elixir有关吗？或者这些只是开发者之间的偏好？我查看了docstrings的样式指南，但看不到它在哪里解决这些问题...
谢谢！
答案 0 :(得分：5)
Python文档字符串可以按照几种格式编写：
历史上， 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
"""
如今，可能更为流行的格式是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 documentation。您可以查看this tuto以获取有关文档字符串的更多信息。
答案 1 :(得分：0)
如果要将文档字符串转换为文档，可以添加额外的标记以帮助您使用的文档工具应用其他格式。
@表示Epydoc个字段。
结肠:首先是狮身人面像（请参阅Sphinx文档或上面的链接。）
此处有相关帖子：What are these tags @ivar @param and @type in python docstring?
可能还有其他用途（可能包括Elixir，它不是我熟悉的可以评论的技术）。
希望有所帮助。