我只是想更好地了解 Python 文档字符串的布局(在 """ """ 之间)
我见过具有不同布局的文档字符串......例如......
"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign
:DESCRIPTION:
Tags with colons
DESCRIPTION
And tags with nothing
"""
这些中是否有任何功能作用？是
@与 Elixir 有关？或者这些只是开发人员的偏好？我已经查看了文档字符串的样式指南，但看不到它在哪里解决这些问题......谢谢!
最佳答案
格式
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
"""
- 休息
如今，可能更流行的格式是 重构文本 Sphinx 使用的 (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推荐跟随自己的 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有关文档字符串的更多信息。
关于formatting - ":"、 "@"和 python 文档字符串中没有的区别，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/23954109/