問題タブ [code-documentation]

.NET ソース内のコード ドキュメントの量が多すぎますか?

いくつかの背景: SO に投稿した他の質問のいくつかで話した大きなコードベースを継承しました。このコードベースの「機能」の 1 つは、God クラスです。これは、数十の静的メソッドを含む 3000 行を超えるコードを持つ単一の静的クラスです。Utilities.CalculateFYBasedOnMonth()からまでのすべてUtilities.GetSharePointUserInfo()ですUtilities.IsUserIE6()。適切なライブラリ セットにリファクタリングするだけで、書き換える必要のない優れたコードです。私はそれを計画しています。

これらのメソッドは新しいビジネス レイヤーに移行しており、このプロジェクトでの私の役割は、他の開発者がシステムを保守できるように準備することなので、しっかりしたコード ドキュメントについて考えています。これらのメソッドにはすべて適切なインライン コメントがありますが、XML コメント形式の適切な (またはまったく) コード doco がすべて含まれているわけではありません。GhostDoc と Sandcastle (または Document X) の組み合わせを使用して、非常に優れた HTML ドキュメントを作成し、それを SharePoint に投稿できます。これにより、開発者は、コード自体をナビゲートしなくても、コードが何をするかをより理解できるようになります。

コード内のドキュメントの量が増えると、コードをナビゲートするのが難しくなります。//commentXML コメントを使用すると、たとえば、各メソッドを単純にするよりも、コードの保守が難しくなるのではないかと考え始めています。

これらの例は、ドキュメント X サンプルからのものです。

と：

だから私はあなたから疑問に思っていました: NDoc (RIP) や Sandcastle のようなものを使用することを目標に、すべてのコードを XML コメントで文書化していますか? そうでない場合、ドキュメントを取得するものと取得しないものをどのように決定しますか? API のようなものには明らかに doco がありますが、別のチームに引き渡して維持するコードベースについてはどうでしょうか?

私は何をすべきだと思いますか？

過去 15 年以上にわたって PHP ドックブロックに携わってきたので、PHP ドックブロックについてはよく知っています。

私が理解しようとしているのは、Delphi や FreePascal にそのような標準があるかどうかです。

非常に多くのコードを分析した結果、見たことはありませんが、完全に間違っている可能性があります。

製品でjava6スクリプトエンジンを使用しており、現在、いくつかのデバッグ機能を追加することを検討しています。

私の質問は：

1. 出来ますか？java 6スクリプトエンジンには、デバッグに関してはrhinoと同じ機能がありますか。
2. それを始める方法についてのいくつかのドキュメント、いくつかのコードサンプルは私がウェブ上で何も見つけることができなかったのでどんな情報でも素晴らしいでしょう。

ありがとう

私たちは C++/C# ライブラリを管理していますが、多くのクラスと関数が文書化されていないことに気付きました。

コードを解析して文書化されていないクラスとメソッドを探し、文書化されていないクラス/メソッド/関数のリストを生成するスクリプトを作成することを考えました。

また、不足しているドキュメントの dOxygen タグを配置するスクリプトも必要です。つまり、そのようなコードが見つかった場合:

それは

もちろん、関数が将来、自動生成されたドキュメント ヘッダーを持っていても、誰もヘッダーに触れていない場合、レポートではドキュメント化されていないと報告されます。

そのようなツールを開発するには、どのスクリプト言語を使用しますか?

アンソニー

重複の可能性:
自動 PHP ドキュメント生成?

私は PHP の初心者であり、現在の仕事では非常に速いペースで言語を習得する必要があります。

私はドキュメンテーションにこだわっています。ドキュメントを書くのも好きです。私は、いくつかの言語で認められているドキュメントの構文とツールに精通しています。

これは PHP には当てはまりません。

文書化可能なソース コード コメントを記述する方法は常に複数あり、通常は言語ごとにさまざまなツールがあることを私は知っています。ただし、私は、標準的なコメント方法や標準の PHP autodoc ツールを義務付けていない環境にいます。これにより、選択の自由が与えられ、それに伴い、分析による麻痺が少し発生します。

phpDocumentor ( http://www.phpdoc.org/ ) は、PHP autodocs の許容可能な標準ツールですか?

PHP コードを文書化するときに、コードに関する一般的な JavaDoc ガイドラインに従うことは許容されますか?

プロジェクト内のクラスごとに、SandCastle は (とりわけ) 2 つのページを作成します。

• と呼ばれるメイン ページにはT_class_full_name、構文、継承階層、および関連項目の説明が含まれています。
• AllMembers_T_class_full_nameコンストラクター、メソッド、フィールドなどを含む、と呼ばれるメンバー ページ。

これら 2 つをマージしmembers pageて、メイン ページに追加する方法はありますか?

Doxygenに完全なインクルードパスを表示させるにはどうすればよいですか？

どういう意味ですか：

次のディレクトリ構造でfoo::bar::bee定義されたクラスがあります。bee.hpp

Doxygen、それfoo::bar::beeがクラスを文書化するとき、あなたが含める必要があると言っています<bee.hpp>、しかし私のソフトウェアのために私は必要です<foo/bar/bee.hpp>

どうすればDoxygenにこれを行わせることができますか？「-I」のような「インクルードフラグ」を提供して、doxygenがベースの場所を認識できるようにするオプションはありますか？

ノート：

• FULL_PATH_NAMESすでにデフォルトに設定されていますYES
• クラスが多すぎるため、クラスごとに明示的にインクルードヘッダーを提供したくありません。Doxygenにこれを自動的に実行させたい。

ありがとう。

答え

セットする：

多くのアセンブリを外部のお客様に提供していますが、すべてのパブリック API が正式にサポートされているわけではありません。たとえば、設計の選択が最適とは言えないため、コードの残りの部分が機能するために型をアセンブリからパブリックに公開する必要がある場合がありますが、顧客にはその型を使用してほしくありません。サポートの欠如を伝える 1 つの部分は、XML コメントの形式でインテリセンスを提供しないことです。

XML コメントを選択的に抑制する方法はありますか? 長期的なメンテナンスの問題であるため、警告 1591 を無視する以外の何かを探しています。

例: パブリック クラス A と B を持つアセンブリがあります。A は公式にサポートされており、XML ドキュメントが必要です。B は外部使用を意図していないため、文書化しないでください。XML ドキュメントをオンにして、警告 1591 を抑制することもできます。しかし、後で公式にサポートされているクラス C を追加するときに、XML ドキュメントの追加に失敗して失敗したことをコンパイラに通知してもらいたいのです。プロジェクト レベルで 1591 を抑制した場合、これは発生しません。クラス全体で #pragma できると思いますが、これを行うためのより良い方法があるはずです。

UILabelの色を変更するための構文は何ですか？

また、この情報はどこにありますか？

JavaScript と PHP の両方のコードのドキュメントを簡単に作成できるツールをご存知ですか?

以下に示すようなコードでコメントを取るもの：

そして、これらを HTML ファイルに変換します (おそらく、左側にフレームセット メニューがあります)。 上記と同じ構文は必要ありません。これは、私が話していることを説明するための単なる例です。

必要なツールは 1 つだけなので、ドキュメントを作成するための構文を習得したら、PHP と JavaScript の両方で同じドキュメント構文を使用できます。

ツールがバイナリ (.exe) または Java コードで、PERL や PYTHON をインストールする必要がない場合は便利です。