8

我只是想更好地了解 Python 文档字符串的布局（在 之间""" """）

我见过具有不同布局的文档字符串......例如......

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

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

这些是否具有功能性作用？@与Elixir有关吗？或者这些只是开发人员之间的偏好？我查看了文档字符串的样式指南，但看不到它在哪里解决了这些问题......

谢谢！

4

2 回答 2

10

格式

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
"""

- 休息

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

- 谷歌

谷歌有他自己的格式，非常常用。它也可以被 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 文档。您可以查看此教程以获取有关文档字符串的更多信息。

于 2014-06-20T12:13:24.130 回答
3

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

用于@指示Epydoc字段。

分号:首先用于 sphinx（请参阅Sphinx文档或上面的链接）。

这里有一个相关的帖子：python docstring 中的 @ivar @param 和 @type 这些标签是什么？

可能还有其他用途（可能包括 Elixir，这不是我熟悉的技术，无法评论）。

希望有帮助。

于 2014-06-20T10:18:47.773 回答