如何为 Python 函数编写帮助/描述文本
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/21930035/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to write help/description text for Python functions
提问by user1984653
I recently started programming using Python. I have to write many functions and was wondering how I can incorporate a help or description text such that it appears in the object inspector of spyder when I call the function. In MatLab, this worked by putting commented text at the beginning of the function file. Is there a similar method in Python (using Spyder)?
我最近开始使用 Python 进行编程。我必须编写许多函数，并且想知道如何合并帮助或描述文本，以便在调用该函数时它出现在 spyder 的对象检查器中。在 MatLab 中，这是通过在函数文件的开头放置注释文本来实现的。Python中是否有类似的方法（使用Spyder）？
采纳答案by Burhan Khalid
By default, the first string in the body of a method is used as its docstring (or documentation string). Python will use this when help()is called for that method.
默认情况下，方法主体中的第一个字符串用作其文档字符串（或文档字符串）。当help()该方法被调用时，Python 将使用它。
def foo(bar):
"""
Takes bar and does some things to it.
"""
return bar
help(foo)
foo(bar)
Takes bar and does
some things to it
You can read more about how this works by reading PEP-258, and this questiongoes into some more details.
回答by Carlos Cordoba
(Spyder maintainer here) There are other couple of things you need to know (besides what @burhan-khalid mentioned) regarding Spyder itself:
（此处是Spyder 维护者）关于 Spyder 本身，您还需要了解其他几件事（除了@burhan-khalid 提到的内容）：
If you want to see your docstrings nicely formatted in the Help pane, you need to write them following the
numpydocstandard, which is explained here. This is a set of conventions used by almost all python scientific packages to write their docstrings. It's not mandatory but we follow it too while converting docstrings (which come in plain text) to html.You have to use Ctrl+Iin front of an object's name to show their help in our Help pane.
如果您想在“帮助”窗格中看到格式良好的文档字符串，您需要按照
numpydoc标准编写它们，这在此处进行了解释。这是几乎所有 python 科学包用来编写文档字符串的一组约定。这不是强制性的，但我们在将文档字符串（以纯文本形式出现）转换为 html 时也遵循它。您必须在对象名称前使用Ctrl+I才能在我们的“帮助”窗格中显示其帮助。
回答by Gerardsson
In a short answer. This can be done by putting text between triple quotes.
简而言之。这可以通过将文本放在三重引号之间来完成。
'''
@param self
'''
You can find a brief example on this link: https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html#
您可以在此链接上找到一个简短的示例：https: //www.jetbrains.com/help/pycharm/creating-documentation-comments.html#
The other answers are more extensive.
其他答案更广泛。
