gpt4 book ai didi

python - 如何注释pydoc的参数

转载 作者:太空狗 更新时间:2023-10-29 17:39:19 28 4
gpt4 key购买 nike

有没有办法注释函数的参数,使它们被 pydoc 库识别?

即 pydoc 的文档字符串是什么?

最佳答案

pydoc 不识别文档字符串中的“结构化”元素,它只是按原样输出文档字符串。有关示例,请参见 PEP-257

如果您想要“格式化”文档,您应该使用另一个文档生成器,例如 Sphinxpdoc

函数的参数必须记录在函数文档字符串中。这是从 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")

这是另一个更明确的例子,如果你想利用具有更多参数描述符的重组文本,例如 :type param::rtype: taken from here

"""
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

您还可以使用不同的文档字符串格式(例如 GoogleNumpy ),我推荐!!!让您的文档字符串更清晰。

希望这对您有所帮助!

关于python - 如何注释pydoc的参数,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/34331088/

28 4 0
Copyright 2021 - 2024 cfsdn All Rights Reserved 蜀ICP备2022000587号
广告合作:1813099741@qq.com 6ren.com