python文档字符串中":“和"@”之间的区别

Question

我只是想对Python的布局有一个更好的感觉(在""" """之间)

我见过不同layouts...such的文档字符串.

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

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

这些都有功能性的作用吗？@是否与药剂相关联？还是这些只是开发人员的首选呢？我已经翻阅了文档字符串的样式指南，但是看不出它在哪里处理这些事情.

谢谢!

Answer 1

格式

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

- Javadoc

从历史上看，类似于javadoc的样式很流行。艾比多克 (用称为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

现在，可能更流行的格式是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
"""

-谷歌

谷歌有自己的格式，这是非常常用的。它也可以被狮身人面像解释。请注意，Numpy建议遵循自己的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
"""

转换/生成

可以使用像就业这样的工具自动将文档字符串生成到尚未记录的Python项目，或者将现有的docstring(可以是多种格式)从一种格式转换为另一种格式。

注意:示例摘自就业文件。有关docstring的更多信息，您可以看到这个图图。

Answer 2

如果要将文档字符串转换为文档，可以添加额外的标记以帮助您使用的文档工具应用其他格式。

@用于指示艾比多克字段。

分号:是sphinx的rst (请参阅狮身人面像文档或上面的链接)。

这里有一个相关的帖子：在中，这些标记是什么？

可能还有其他用途(可能包括药剂，我还不太熟悉这一技术，可以对此发表评论)。

希望这能有所帮助。