web-dev-qa-db-ja.com

python関数パラメータタイプを文書化する方法は？

パラメータはどのオブジェクトでもかまいませんが、ドキュメントでは、期待するものを指定することが非常に重要です。

まず、以下のようなパラメータタイプを指定する方法は？

  • str（またはStringまたはstringを使用しますか？）
  • int
  • list
  • dict
  • 関数（）
  • Tuple
  • クラスMyClassのオブジェクトインスタンス

次に、intまたはstrよりも単一のパラメーターを処理できる関数のように、複数のタイプのパラメーターを指定するにはどうすればよいですか？

以下の例を使用して、提案されたソリューションでこれを文書化するために必要な構文を示してください。ドキュメント内から「Image」クラスへの参照をハイパーリンクできることが望ましいことに注意してください。

def myMethod(self, name, image):
    """
    Does something ...

    name String: name of the image
    image Image: instance of Image Class or a string indicating the filename.

    Return True if operation succeeded or False.
    """
    return True

要件に対応できる限り、ドキュメントツール（sphinx、oxygenなど）の使用を提案することを歓迎します。

更新：

一般に、doxygenのパラメータタイプを文書化するための何らかのサポートがあることを示しています。以下のコードは機能しますが、パラメータ名に迷惑な$を追加します（最初はphp用に作成されたため）。

    @param str $arg description
    @param str|int $arg description
pythondoxygen
16
sorin

より良い方法があります。を使用しております

def my_method(x, y):
    """
    my_method description

    @type x: int
    @param x: An integer

    @type y: int|string
    @param y: An integer or string

    @rtype: string
    @return: Returns a sentence with your variables in it
    """

    return "Hello World! %s, %s" % (x,y)

それでおしまい。 PyCharmではIDEこれは大いに役立ちます。それは魅力のように機能します;-)

13
Tony Melony

正しく解析するには、DoxygenのPython docstringの先頭に感嘆符を追加する必要があります。

def myMethod(self, name, image):
    """!
    Does something ...

    @param name String: name of the image
    @param image Image: instance of Image Class or a string indicating the filename.

    @return Return True if operation succeeded or False.
    """
    return True
6
docu

Python 3）を使用する場合は、 PEP 3107 で説明されている関数アノテーションを使用できます。

def compile(
   source: "something compilable",
   filename: "where the compilable thing comes from",
   mode: "is this a single statement or a suite?"):

関数定義 も参照してください。

4
robert

DoxygenはC++に最適ですが、ほとんどpythonコードを使用している場合は、 sphinx を試してみてください。sphinxを選択した場合は、次の手順を実行するだけです。 pep8 。

1
Tom

IDEAはこれが可能であることを示したので、このちょっとした情報をここに投稿すると思いました。

>>> def test( arg: bool = False ) -> None: print( arg )

>>> test(10)
10

test(と入力すると、IDLEのドキュメントヒントが(arg: bool=False) -> Noneとともに表示されます。これは、VisualStudioだけが実行したと思っていたものです。

これは正確にはdoxygenマテリアルではありませんが、コードを使用している人のパラメータータイプを文書化するのに適しています。

0
Tcll

はい、@ docuは正しいです-これは、両方のドキュメントスキームを多かれ少なかれシームレスに組み合わせる（IMHOの最良の）方法です。一方、doxygenで生成されたインデックスページにテキストを配置するようなこともしたい場合は、次のように追加します。

##
# @mainpage (Sub)Heading for the doxygen-generated index page
# Text that goes right onto the doxygen-generated index page

Pythonコードの先頭のどこかにあります。

言い換えると、doxygenがPythonコメントを期待しない場合は、##を使用して、タグがあることを警告します。期待する場合Pythonコメント（関数またはクラスの先頭など）には、"""!を使用します。

0
user147058