11

DRYを適用するために、パラメーターを宣言するのと同じ行に（必要に応じて）各パラメーターを文書化することを好みます

私がこのようなコードを持っている場合：

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

doc文字列でパラメーターを繰り返さないようにし、パラメーターの説明を保持するにはどうすればよいですか？

避けたい：

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
    ):
    '''Foo does whatever.

    * flab_nickers - a series of under garments to process
    * needs_pressing - Whether the list of garments should all be pressed.
      [Default False.]

これは、Python2.6またはPython3で、ある種のデコレータ操作を使用して可能ですか？他に方法はありますか？

4

3 に答える 3

8

私はこれをします。

このコードから始めます。

def foo(
        flab_nickers, # a series of under garments to process
        has_polka_dots=False,
        needs_pressing=False  # Whether the list of garments should all be pressed
   ):
    ...

関数パラメーターの定義を取得して以下を構築するパーサーを作成します。

def foo(
        flab_nickers, 
        has_polka_dots=False,
        needs_pressing=False,
   ):
   """foo

   :param flab_nickers: a series of under garments to process
   :type flab_nickers: list or tuple
   :param has_polka_dots: default False
   :type has_polka_dots: bool
   :param needs_pressing: default False, Whether the list of garments should all be pressed
   :type needs_pressing: bool
   """
    ...

これは、ドキュメントテンプレートに入力するための、さまざまな引数の文字列パターンの非常に単純な正規表現処理です。

多くの優れたPythonIDE（PyCharmなど）は、デフォルトのSphinxparam表記を理解し、IDEが宣言された型に準拠していないと考えるスコープ内の変数/メソッドにフラグを立てます。

コード内の余分なコンマに注意してください。それは物事を一貫させるためだけです。害はなく、将来的には単純化される可能性があります。

Pythonコンパイラを試して使用して、解析ツリーを取得し、それを修正して、更新コードを発行することもできます。私は他の言語（Pythonではない）でこれを行ったので、それについては少し知っていますが、Pythonでどれだけサポートされているかはわかりません。

また、これは1回限りの変換です。

関数定義の元のインラインコメントは、非公式な言語でのコメントであり、最も洗練されたツール以外では使用できないため、実際にはDRYに準拠していません。

SphinxコメントはRSTマークアップ言語であるため、DRYに近く、の通常のテキスト解析ツールを使用して処理するのがはるかに簡単になりますdocutils。

ツールがそれを利用できる場合にのみ、DRYです。

便利なリンク： https ：//pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

于 2010-02-03T19:27:46.990 に答える
5

アノテーションは、Python3でこの問題に部分的に対処することを目的としています。

http://www.python.org/dev/peps/pep-3107/

これらをSphinxに適用する作業がまだあるかどうかはわかりません。

于 2013-08-26T19:57:50.443 に答える
1

ソースがコンパイルされるとPythonのコメントは存在しないため、プリプロセッサなしではこれを行うことはできません。繰り返しを避けるために、コメントを削除し、パラメータをdocstringにのみ文書化してください。これは、引数を文書化するための標準的な方法です。

于 2010-02-03T19:31:45.980 に答える