Python代码中注释和文档字符串的基本语法 [英] Basic Syntax of comments and docstrings in Python code
本文介绍了Python代码中注释和文档字符串的基本语法的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!
问题描述
我正在学习如何使用Sphinx为我的代码创建文档。在我看到一些这样的例子后:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
评论中使用了什么语言来使Sphinx理解并捕捉它们? 如果没有这种语法和逻辑,Sphinx就看不到我代码中的注释,并且当我生成HTML时,该模块是空的。
这里有一个例子:
推荐答案
您必须区分注释和文档字符串(全称为文档字符串)。
请参阅PEP8 and notice docstrings apply only to模块、函数、类和方法。对于提到的对象,您可以应用your_object.__doc__
以编程方式检索文档字符串;变量没有文档字符串。
关于您的示例:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
Sphinx将检索的文档字符串中可以使用3种流行语法:
- REST是基本语法。
- Numpy样式的文档字符串。
- Google风格的文档字符串。
规范是在Numpy或Google Style之间选择(目前它们提供了更好的可读性和功能,以及一个样式指南)。要使这些功能正常工作,您需要使用Sphinx-Napoleon extension,请查看官方文档中的概述。
这篇关于Python代码中注释和文档字符串的基本语法的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!
查看全文