同じ関数で異なる引数の可能性を文書化する

Question

私はsphinx.ext.autodocでGoogleスタイルのドキュメントストリングを使用して、自分の関数のドキュメントを自動的に生成し、コード内に正しく文書化されていることを確認します。

私はidまたはsize + hashに基づいて情報を返す関数def myfunc(id=None, size=None, hash=None)を持っています。引数としてidがある場合、sizeとhashは必要ありません。引数としてsizeとhashがある場合、idは必要ありません。

sphinxでは、オプションの引数を指定することはできますが、この場合、必須となるものとオプションのものは分かりません。ここでは例です：

def get_file(id=0, size=0, hash="") 
    """ 
    Get file metadata. 

    Args: 
     id (int): id of the file. 
     size (int): file size in bytes. 
     hash (str): md5 hash of file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 
    if id: 
     # Get file with id. 
     ... 
    elif size and hash: 
     # Get file with size and hash. 
     ... 
    else: 
     # Bad arguments, handle error. 
     ... 

    return file_data 

質問です：のdocstringに必要なものを引数伝えるためにどのように？

あなたは関数自体は、両方の引数のペアは、結果は同じであっても、別の関数でなければならないこと、問題であることを簡単に主張することができます：

def get_file_by_id(id) 
    """ 
    Get file metadata from id. 

    Args: 
     id (int): id of the file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 

    # Get file with id. 
    ... 

    return file_data 

def get_file_by_hash(size, hash) 
    """ 
    Get file metadata from hash. 

    Args: 
     size (int): file size in bytes. 
     hash (str): md5 hash of file. 

    Returns: 
     file_data (str): metadata information about the file. 
    """ 

    # Get file with hash+size. 
    ... 

    return file_data 

しかし、この場合には、単一の関数は次のようになりますできるだけ優先されるのは、関数が単一の関数を使用する別のAPIへのバインディングであるためです。

Answer 1

がドキュメント、hereによると、次の例のメソッド定義は：

def module_level_function(param1, param2=None, *args, **kwargs): 

はドキュメンテーション文字列のように定義している：だから、あなたが明示的に示されているようにオプションが何であるかを述べる

Args: 
    param1 (int): The first parameter. 
    param2 (:obj:`str`, optional): The second parameter. Defaults to None. 
     Second line of description should be indented. 
    *args: Variable length argument list. 
    **kwargs: Arbitrary keyword arguments. 

、それ以外の場合は、必須の引数として理解されます。