問題タブ [code-documentation]

「Docbook」や「doxygen」などの C、C++、および Java コードのドキュメント化に適したツールはどれですか?他のツールを教えてください。

私が理解しているように、「javadoc」は、javadocという名前でも呼ばれるhtmlドキュメントを生成するツールの名前です。少なくとも私はそのように言葉を使ってきました..

しかし、ツール doxygen の生成された出力は何と呼ばれますか? Doxygen-doc? doxy-doc? それとも何か他のものですか？

(問題がある場合は、C++ コンテキストでの質問)

まず、この質問では、ソース コードのコメントが良いか悪いかという論争から離れたいと思います。なぜ、何を、どのように伝えるコメントについて話しているときに、人々が何を意味するのかをより明確に理解しようとしているだけです。

「コメントは理由を教えてくれ、コード自体が方法を教えてくれるはずだ」というようなガイドラインをよく目にします。抽象的なレベルでのステートメントに同意するのは簡単です。しかし、人々は通常、これをドグマのように落とし、それ以上の説明なしに部屋を出ます。これが非常に多くの異なる場所や文脈で使用されているのを見てきました。人々はキャッチフレーズに同意できるように見えますが、まったく異なることについて話しているようです.

では、質問に戻ります: コメントが理由を教えてくれるとしたら、私たちが話している理由は何ですか? これが、そもそもそのコードが存在する理由ですか? これは、そのピースコードがすべきことですか? 誰かが明確な説明をしてから、いくつかの良い例を追加していただければ幸いです (悪い例は実際には必要ありませんが、対比のために自由に追加してください)。

この質問を重複または論争としてすぐに閉じないでください。私はそれを非常に客観的にするために一生懸命努力しました。コメントが良いか悪いかについては多くの質問がありますが、理由を示すコメントの良い例は何かという具体的な質問に答えている人は誰もいません。

ありがとう、

ここで素晴らしい記事を見つけました：

http://www.codeproject.com/Articles/18204/ASP-NET-controls-to-display-enum-values

そこで私はそれを研究し、多くのことを学び、それを新しいクラス ライブラリとして Visual Studio ソリューションに組み込みました。

コードを借用して Web アプリケーションで利用した後、CodeProject の元の記事を私の Visual Studio ソリューション (複数のプロジェクト) にリンクして、後で私と私のチームが参照できるようにこの記事を「ブックマーク」できる最善の方法は何ですか?のメンバーであり、アイデアを思いついた元の開発者の功績を称えます。私が持っていた 1 つのアイデアは、EnumControls クラス ライブラリの AboutBox でしたが、考えれば考えるほど、それは少しばかげているように思えます (設計時に同僚や将来の漏れやすい脳のためにドキュメントを利用できるようにしたいだけです)。

しばらくの間、behaviour_info/1 の代わりに -callback 属性を使用して動作コールバックを宣言できるようになりました (私の意見では、こちらの方が便利です)。しかし、edoc アプリケーションはそのような属性を検出できないようです。それでも、リリース ノートによると、この問題はバージョン 0.7.10 ( http://www.erlang.org/doc/apps/edoc/notes.html ) で既に修正されています。誰かが同様の問題に遭遇し、それを克服できましたか?

1 つの文字列パラメーターを受け入れる関数があります。このパラメーターは、いくつかの定義された可能な値のうちの 1 つだけを持つことができます。同じことを文書化する最良の方法は何ですか? shapeType は、列挙型または TypeDef などとして定義する必要がありますか?

問題の 2 番目の部分は、提案されたものとして定義されているファイルで、 の可能な値shapeTypeが不明であることです。shapeTypeの可能な値に追加する可能性のある複数の開発者によって提供された複数のファイルがありますshapeType。

PS：使用していますjsdoc3

JS ライブラリで特定のモジュールを自動化しようとしていますが、一連のプロパティ (クラスの構築パラメータとして使用されるオブジェクトとしましょう) を定義したいところで行き詰っています。

構成のすべてのプロパティが 1 つの場所で定義されていれば、それで十分です。残念ながら、私のコードには、その構築プロパティに貢献する多くのモジュールがあります。たとえば、コードの他の部分 (後のファイル) で、さらにいくつかのプロパティが発生するとします。

WorldPeace関数に対して以前に定義したプロパティの元のセットに追加するにはどうすればよいですか? ミックスインやプロパティのサブクラス化のようなことを行うのは、行き過ぎです! そのため、単純にプロパティ リストの定義に注入できれば、それは素晴らしいことです。