python 是否具有与 javascript 等效的函数注释？

Question

在 Javascript 中，编码人员可以使用 @param 和 {string} 选项对函数进行如下注释。

Python 有文档字符串，但是阅读 https://www.python.org/dev/peps/pep-0257/ 文档字符串约定我看不到与 js.

等价的内容

这里是一个注释 JS 函数的例子：

/**
 * generate a random matrix
 * @param {number} n the height of the matrix
 * @param {number} m the width of the matrix
 */
function generateRandomMatrix(n, m) {
    mtrx = []
    for (let i = 0; i < n; i++) {
        mtrx.push([])
        for (let j = 0; j < m; j++) {
            mtrx[i].push(Math.round(Math.random()*10))
        }
    }
    return mtrx
}

上面的评论的 python 等价物是什么（如果存在）？特别是 @param 和 {number} 功能....

Answer 1

你可以在Python中这样写：

def get_full_name(first_name, last_name):
    """
    Construct full name from last name and first name

    :param first_name: first name of Person 
    :param last_name: last name of Person
    :return: concatenation of first and last name of Person
    """
    return first_name + last_name

Pycharm 与 python 文档字符串的集成非常好，可以为您完成大量手动工作。有很多可能的格式。上面的示例显示了 Sphinx 用于生成文档的可能更普遍的格式。

看看这个很好的描述：What is the standard Python docstring format?

Answer 2

是的。它们被称为文档字符串。参见 https://www.python.org/dev/peps/pep-0257/

def foo(bar: int, baz: int) -> int:
    """
    Add two numbers

    :param bar: explain bar
    :param baz: explain baz
    :return: int
    """
    return bar + baz

Answer 3

Python 中关于函数参数的注释也应包含在文档字符串中，然后您可以使用 Sphinx 自动生成文档。 Sphinx 最初是为 Python 文档本身创建的。

默认情况下，Sphinx 采用以下格式的文档字符串（参见 here）：

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]

但是你可以使用 Napoleon extension for Sphinx to read the much more readable (and therefore Pythonic) Google Style Docstrings:

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.
    """

Answer 4

在python中，您将在文档字符串中这样评论。

def generate_random_matrix(n, m):
    """generate a random matrix

     Parameters
     -----------------
     n : int
         the height of the matrix
     m : int 
         the width of the matrix

     Returns
     ----------
     An array with shape (n, m)
    """
    pass

这里有几个指南可以看看anwser。

Answer 5

Python有两种评论。一个用于片段或单行注释 (#)，另一个用于多行。

你需要的是第二个：

def pyhton_function(parameter1):
"""
This type of comment is preferable for longer text and function description.

Function returns double the parameter 1 received

"""
return parameter1

可能值得注意的是，“ ”内的任何内容都不能是注释。即：

print("#this is not a comment")

python 是否具有与 javascript 等效的函数注释？

does python have an equivalent function comment to javascript?

javascript

python

docstring

node.js

python-3.x