Python 如何注释pydoc的参数
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/34331088/
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 comment parameters for pydoc
提问by PatriceG
Is there a way to comment the parameters of a function to make them recognized by the pydoc library ?
有没有办法注释函数的参数，使它们被 pydoc 库识别？
i.e what is the docstring for pydoc?
即 pydoc 的文档字符串是什么？
采纳答案by Ire
pydoc doesn't recognise "structured" elements in docstrings, it just outputs the docstring as is. See PEP-257for an example.
pydoc 不识别文档字符串中的“结构化”元素，它只是按原样输出文档字符串。有关示例，请参阅PEP-257。
If you want a "formatted" documentation you should use another documentation generator, such as Sphinxor pdoc, for example.
如果你想要一个“格式化”的文档，你应该使用另一个文档生成器，例如Sphinx或pdoc。
The parameters for functions have to be documented in the functions docstring. Here is an example taken from this answer:
函数的参数必须记录在函数文档字符串中。这是从这个答案中获取的一个例子：
"""
This example module shows various types of documentation available for use
with pydoc. To generate HTML documentation for this module issue the
command:
pydoc -w foo
"""
class Foo(object):
"""
Foo encapsulates a name and an age.
"""
def __init__(self, name, age):
"""
Construct a new 'Foo' object.
:param name: The name of foo
:param age: The ageof foo
:return: returns nothing
"""
self.name = name
self.age
def bar(baz):
"""
Prints baz to the display.
"""
print baz
if __name__ == '__main__':
f = Foo('John Doe', 42)
bar("hello world")
Here is another more explicit example if you want to take advantage of restructured text with more parameter descriptors, such as :type param:or :rtype:taken from here
如果您想利用具有更多参数描述符的重组文本（例如:type param:或:rtype:取自此处），这是另一个更明确的示例
"""
The ``obvious`` module
======================
Use it to import very obvious functions.
:Example:
>>> from obvious import add
>>> add(1, 1)
2
This is a subtitle
-------------------
You can say so many things here ! You can say so many things here !
You can say so many things here ! You can say so many things here !
You can say so many things here ! You can say so many things here !
You can say so many things here ! You can say so many things here !
This is another subtitle
------------------------
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
"""
def add(a, b):
"""
Adds two numbers and returns the result.
This add two real numbers and return a real result. You will want to
use this function in any place you would usually use the ``+`` operator
but requires a functional equivalent.
:param a: The first number to add
:param b: The second number to add
:type a: int
:type b: int
:return: The result of the addition
:rtype: int
:Example:
>>> add(1, 1)
2
>>> add(2.1, 3.4) # all int compatible types work
5.5
.. seealso:: sub(), div(), mul()
.. warnings:: This is a completly useless function. Use it only in a
tutorial unless you want to look like a fool.
.. note:: You may want to use a lambda function instead of this.
.. todo:: Delete this function. Then masturbate with olive oil.
"""
return a + b
You can also use different docstring formats (like Googleor Numpy), which I recommend!!!to make your docstrings clearer.
您还可以使用不同的文档字符串格式（如Google或Numpy），这是我推荐的！！！使您的文档字符串更清晰。
Hope this helps!
希望这可以帮助！
回答by mrDinkelman
Another example
另一个例子
#!/usr/bin/env python
"""
Module documentation
A small example of comments usage
"""
# regular comment,
# will not visible by pydoc
spam = 40
def square(x):
"""
this function will return square(x) value
:param x: any number
:return: example doc for return
"""
return x ** 2
import abc
class ListInherited:
"""
Class ListInherited doc example
This class use dir() function for list instance attributes
"""
def __init__(self, arg1):
"""
my constructor
:param arg1: example value
:return:
"""
self.arg1 = arg1
def __str__(self):
"""
to string conversion
:return:
"""
tup = (self.__class__.__name__, id(self), self.attr_names())
return '<Instance of %s, address %s:\n%s>' % tup
def attr_names(self):
"""
get attribute names
:return: string
"""
result = ''
for attr in dir(self):
if attr[:2] == '__' and attr[-2:] == '__': # skip "build-in"
result += '\t name %s=<>\n' % attr
else:
result += '\t name %s=%s\n' % (attr, getattr(self, attr))
return result
@staticmethod
def my_static_method(count):
"""
static method comment example
:param count:
:return:
"""
return "Hello, I'm static" * count
if __name__ == "__main__":
import test3
x = 33
y = test3.square(x)
print(test3.__doc__)
print(test3.square.__doc__)
instance = ListInherited(1)
print(instance.__doc__)
In python console
在 python 控制台中
>>> import test3
>>> help(test3)
Output:
输出：
Help on module test3:
NAME
test3
FILE
/home/mrdinkelman/PycharmProjects/testproject27/test3.py
DESCRIPTION
Module documentation
A small example of comments usage
CLASSES
ListInherited
class ListInherited
| Class ListInherited doc example
| This class use dir() function for list instance attributes
|
| Methods defined here:
|
| __init__(self, arg1)
| my constructor
| :param arg1: example value
| :return:
|
| __str__(self)
| to string conversion
| :return:
|
| attr_names(self)
| get attribute names
| :return: string
|
| ----------------------------------------------------------------------
| Static methods defined here:
|
| my_static_method(count)
| static method comment example
| :param count:
| :return:
FUNCTIONS
square(x)
this function will return square(x) value
:param x: any number
:return: example doc for return
DATA
spam = 40
