問題タブ [docstring]

私は、C または PHP コードのドキュメントを作成するために Doxygen が好きです。/* .. */私は近日中に Python プロジェクトを予定していますが、Python にはコメントがなく、独自の自己文書化機能も備えていることを覚えていると思います。

私は Doxygen に精通しているので、それを使用して Python ドキュメントを作成するにはどうすればよいですか? 特に注意しなければならないことはありますか？

docstring がモジュールまたは関数を記述するのと同様の方法で、モジュールのデータを記述する方法はありますか?

あなたの意見では、意味のあるdocstringは何ですか? あなたはそこで何を説明することを期待していますか?

たとえば、この Python クラスの を考えてみましょう__init__:

これは意味があると思いますか？あなたの良い/悪い例を投稿して、すべての人に知ってもらいます（そして、それが受け入れられるように一般的な回答を投稿してください）.

Python コードの大きなブロックをコメントアウトするメカニズムはありますか?

現在、コードをコメントアウトする唯一の方法は、すべての行を で始めるか#、コードを三重引用符で囲むことです: """.

これらの問題は、すべての行の前に挿入するの#が面倒で"""、コメントとして使用したい文字列が生成されたドキュメントに表示されることです。

すべてのコメントを読んだ後、答えは「いいえ」のようです。

このようなコードをテストする最良の方法は何ですか (オブジェクトが毎回異なるブロックで作成されている間、以下のコードは明らかに失敗します):

VIM で Python を記述しているときに、関数のドキュメント文字列を表示する方法はありますか?

例えば：

MyFunction(spam0)ツールチップ、ステータス バー、または VIM で許可されているその他の方法で、doc 文字列を入力して表示できるようにしたいと考えています。

簡単な方法でドキュメント文字列を名前付きタプルに追加することは可能ですか?

私は試した

しかし、それはそれをカットしません。他の方法で行うことは可能ですか？

このようなものを書くことは有効なJavaScriptです：

文字列は実際には何もしません。JavaScriptで自分の関数をこのようにコメントしてはいけない理由はありますか？

質問をしている間に私が考えることができる2つのポイント：

• 文字列リテラルを開始する必要がありますが、これは長期的にはコストがかかる可能性があります

• 文字列リテラルは、JSミニファイアによってリムーバブルとして認識されません

他に何かポイントはありますか？

編集：このトピックを取り上げた理由： John Resigのブログでこのようなものを見つけました。新しいECMA5標準では、割り当てられていない文字列リテラルを使用して「厳密モード」を有効にしています。今、そのような文書化を行うことに使用または危険があるかどうかを評価することが私の興味でした。

Pythonプロジェクトのテストの数と質を改善しようとしています。テストの数が増えるにつれて私が遭遇した困難の1つは、各テストが何をするのか、そしてそれが問題を見つけるのにどのように役立つのかを知ることです。テストを追跡することの一部は、より良い単体テスト名（他の場所で対処されています）であることを知っていますが、ドキュメントと単体テストがどのように連携するかを理解することにも興味があります。

ユニットテストを文書化して、それらのテストが将来失敗した場合の有用性を向上させるにはどうすればよいですか？具体的には、優れた単体テストdocstringを作成するものは何ですか？

説明的な回答と、優れたドキュメントを備えた単体テストの例の両方をいただければ幸いです。私はPythonのみを使用していますが、他の言語からの練習も受け付けています。

デコレータで docstring を使用する際に問題があります。次の例を考えます。

foo期待どおりの docstring がヘルプに表示されなくなりました。次のように表示されます。

デコレータがなければ、ヘルプは正しいです:

関数fooはデコレータによってラップされているため、関数オブジェクトはもはや関数ではありませんfoo。しかし、期待どおりにドキュメント文字列 (およびヘルプ) を取得するための優れたソリューションは何ですか?