我只是想更好地了解 Python 文档字符串的布局（""" """ 之间）
我见过具有不同布局的文档字符串...例如...
"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign
:DESCRIPTION:
Tags with colons
DESCRIPTION
And tags with nothing
"""
这些是否有功能性作用？ @ 是否与 Elixir 相关联？或者这些只是开发人员之间的偏好？我已经查看了文档字符串的样式指南，但看不到它在哪里解决了这些问题......
谢谢！
【问题讨论】：
标签： formatting documentation docstring python-elixir
如果您想将文档字符串转换为文档，您可以添加额外的标记来帮助您正在使用的文档工具应用额外的格式。
@ 表示Epydoc 字段。
分号 : 是 sphinx 的第一个（参见 Sphinx 文档或上面的链接）。
这里有一个相关的帖子：What are these tags @ivar @param and @type in python docstring?
可能还有其他用途（可能包括 Elixir，这不是我熟悉的技术，无法评论）。
希望对您有所帮助。
【讨论】：
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
"""
如今，可能更流行的格式是 reStructuredText (reST) 格式，Sphinx 使用它来生成文档。
例子：
"""
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
"""
Google 有自己的格式，非常常用。它也可以被 Sphinx 解释。请注意，Numpy 建议遵循他们自己的基于 Google 格式且可供 Sphinx 使用的 numpydoc。
例子：
"""
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 了解有关文档字符串的更多信息。
【讨论】：