我只是想更好地感受Python文档字符串的布局(之间""" """
)
我见过不同布局的docstrings ......比如...
""" @DESCRIPTION Ive seen tags STARTING with an at-sign :DESCRIPTION: Tags with colons DESCRIPTION And tags with nothing """
这些都有功能吗?是@
用药剂关联?或者这些只是开发者之间的偏好?我查看了docstrings的样式指南,但看不到它在哪里解决这些问题......
谢谢!
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 """
如今,可能更普遍的格式是sphinx用于生成文档的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 """
谷歌有自己的格式,很常用.它也可以由Sphinx解释.请注意,Numpy建议您遵循自己的基于Google格式的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文档.你可以看到这个tuto有关docstrings的更多信息.