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

Комментарии об аргументах для функций в Python также должны быть включены в строки документации, и тогда вы можете использовать Sphinx для автоматического создания документации. Sphinx изначально был создан для самой документации Python.

По умолчанию Sphinx принимает следующий формат строки документации (см. здесь ):

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

Но вы можетеиспользуйте расширение Наполеон для Сфинкса , чтобы прочитать гораздо более читаемый (и, следовательно, Pythonic) Строки документации Google Style :

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 3

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

Answer 4

Да. Они называются струнами документов. Смотри 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 5

Вы можете написать что-то вроде этого в 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 для генерации документации.

Взгляните на это хорошее описание: Что такое стандартный формат документации Python?