2012-02-22 9 views
8

私は私が書いたパッケージに、いくつかの(epydoc)のドキュメントを追加している、と私は自分自身に多数回繰り返してるのインスタンスがたくさん渡って来ています。ドキュメンテーション文字列 - 複数行対1つのライン

def script_running(self, script): 
    """Return if script is running 

    @param script: Script to check whether running 

    @return: B{True} if script is running, B{False} otherwise 
    @rtype: C{bool} 
    """ 

PEP257ことを言う:

ワンライナーは本当に明白な例のためのものです。

とも

その動作を要約して上でその引数、戻り値(s)は、副作用、発生した例外、および制限を文書化する必要がある関数やメソッドのdocstringは、それを呼び出すことができます(該当する場合はすべて)。


ワンライナー(説明)とフルのparam /リターン・フィールドの間に線を描画するときのための一般的なガイドラインや標準的な方法はありますか?

やドキュメントを生成し、私は関係なく、それはそうか、繰り返しの、各機能ごとに適用可能なフィールドを含める必要がありますか?

ボーナス質問:構文上、scriptのparamを記述するための最良の方法は何ですか?

答えて

16

あなたが探している一般的なガイドラインは、あなたが引用されたものの中にPEP257に多分あなただけのアクションでそれを見る必要が権利です。

あなたの関数は、1行のドキュメンテーション文字列(「本当に明白な例」)のための良い候補である:あなたは機能が何かをチェックしていると言うなら、それは返すために起こっていることを意味通常

def script_running(self, script): 
    """Check if the script is running.""" 

TrueまたはFalseが、あなたが好きなら、あなたはより具体的な可能性:

def script_running(self, script): 
    """Return True if the script is running, False otherwise.""" 

もう一度、すべて1行で。

関数は、その名前(スクリプト)にどのような作品を重視する必要はありませんので、私はおそらく、あなたの関数の名前を変更します。関数名は、関数が何をするかについて、甘くて短く、意味があるものでなければなりません。おそらく、私は行くよ:は、全ての符号化によって疲れている

def check_running(self, script): 
    """Return True if the script is running, False otherwise.""" 

時々関数名-想像力が、あなたは自分のベストを尽くすために、とにかく試してみてください。

は複数行たとえば、私はgoogle guidelinesからドキュメンテーション文字列を借りる:

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. 

    Returns: 
     A dict mapping keys to the corresponding table row data 
     fetched. Each row is represented as a tuple of strings. For 
     example: 

     {'Serak': ('Rigel VII', 'Preparer'), 
     'Zim': ('Irk', 'Invader'), 
     'Lrrr': ('Omicron Persei 8', 'Emperor')} 

     If a key from the keys argument is missing from the dictionary, 
     then that row was not found in the table. 

    Raises: 
     IOError: An error occurred accessing the bigtable.Table object. 
    """ 

これはへの一つの方法かもしれない「その振る舞いを要約し、その引数、戻り値(s)は、副作用を文書化し、発生した例外、および呼び出すことができるときの制限(該当する場合すべて)」

このexample of pypi projectは、Sphinxと記載されていることをご確認ください。

私の2セント:ガイドラインあなたがしてやるべきではないすべきかについてのアイデアを与えることを意図しているが、彼らはあなたが盲目的に従わなければならない厳格なルールではありません。だから最後にあなたが良いと感じるものを選んでください。


私はドキュメンテーション文字列で行の最大長を打つ程度別の答えに言われているものをクリアしたいと思います。

-------------------------------------------------------------------------------- 

そして、これがことがあります

PEP8は最後に誰もがこれは80 charachters 80

あるんにもかかわらず「リミット79文字の最大のすべての行を」を示しています少し長い文が本当に必要な辺の場合:

def my_long_doc_function(arg1, arg2): 
    """This docstring is long, it's a little looonger than the 80 charachters 
    limit. 

    """ 

1行のようなものですdocstringは、本当に明白な場合はの場合はを意味しますが、エディタ(80文字の制限あり)は複数の行にあります。

4

私はdocstringのための拡張構文を追加する際に関与繰り返し、ある程度の、即ちepydoc /スフィンクスのマークアップは、常に可能性があると思います。

私はこの問題は客観的なものよりも主観的なものだとも言います。 Explicitは暗黙的よりも優れており、PythonのZenに続きます。

関連する問題