在Pythons Epydoc中记录段落之间的标记

Question

我正在为python中的方法编写文档，这些文档应该可供最终用户阅读。我正在使用Epydoc字段标记来记录基于给我的需求的参数，并尝试将参数描述放在方法描述和使用方法的示例之间，如下所示：

"""
A description of what this utility does.


@param utilityArguments: Description of arguments
@type utilityArguments: String


A list of examples:

example1

example2

example3

"""

不幸的是，我没有成功地找到一种方法来排除类型标记中的示例，它们被添加到类型标记中，而不是分开。我尽量不将参数移动到参数的末尾，因为我们觉得这看起来更整洁；有没有办法终止文档标记并排除其中的任何后续文本？

Answer 1

很抱歉成为坏消息的传播者，但是Epydoc documentation明确禁止这种行为：

字段必须放在文档字符串的末尾，在对象描述之后。字段可以按任何顺序包含。

由于字段都是@param和@return标记，这意味着一个字段后面的所有内容都将被视为该字段的一部分(除非它是另一个字段)。