在同一函數中記錄不同的參數可能性

Question

我使用Google風格的文檔字符串與sphinx.ext.autodoc自動生成我的函數的文檔，並確保它們在代碼中正確自我記錄。

我有一個函數def myfunc(id=None, size=None, hash=None)，基於id或size + hash返回信息。如果我們有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 

的問題是：如何分辨哪些參數是必要的文檔字符串？

你可以很容易得出該函數本身就是問題，這兩個參數對應該在各自獨立的功能，即使結果是一樣的：

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. 

因此，可以明確的是可選所示，否則將被理解爲強制性的論點。