問題タブ [documentation]

JavaDocが生成するものと同様のシェルスクリプトを文書化できるオープンソースまたはパブリックドメインのフレームワークはありますか？これを特定の種類のシェルスクリプトだけに限定する必要はありません。理想的には、拡張が簡単な、または自己文書化の方が優れているWebページでAPIまたはコマンドラインタイプのコマンドを文書化するための汎用フレームワークが必要です。

CACMの記事から、DoxygenはJava（および他のいくつかの言語）でも動作することがわかりました。しかし、JavaにはすでにJavadocツールがあります。誰かがどちらのアプローチの長所と短所を説明できますか？それらは相互に排他的ですか？Doxygen用のMavenプラグインはありますか？

Visual Studio がそれを行います。リフレクターがそれを行います。そして今、私もそうしたい:)

一部のフレームワーク アセンブリ ( 、 など) の一部のメンバーの XML ドキュメントを取得したいと考えていmscorlib.dllますSystem.dll。これには次のことが含まれると思います。

• アセンブリの XML ファイルを検索し、
• 適切な名前の子要素に移動し、
• 目的のアイテムの取得 ( <summary>、<remarks>など)

フレームワーク アセンブリの XML ファイルはどこに保存されますか? XMLDOC 命名スキームを解読する際のポイントはありますか? このプロセスを簡単にするライブラリはありますか?

私は自分のプロジェクトを規律し、最初からビジョン/スコープの文書を作成することに力を注いでいます。これには、ユースケース図が含まれています。ユースケースをリストアップするだけで、顧客が求めているすべての要件を完全に理解することができ、対話が開かれました。

ユースケースをどの程度詳細に記述すべきか疑問に思っています。Web アプリケーションを作成していて、ユーザーがログインしてレポートを表示する場合、レポートのすべての列をユース ケースの説明に記載する必要がありますか?

そうでない場合、いつそれらの詳細を文書化しますか?

メソッドやクラスなどを文書化するときに、いくつかのパラメーターや例外スロー (またはその他のもの) を誤って説明するのを忘れる場合があります。

欠落しているドキュメント項目について警告するように javadoc を実行することは可能ですか?

(ドキュメントの生成には ant スクリプトを使用します)

ウィキペディアには、科学分野で使用されている引用が多数掲載されていますが、コンピュータ サイエンスやソフトウェア エンジニアリング関連のドキュメントで際立っているものはありますか? 私の最初の推測では、両方の分野に関連する会議や出版物が多数あるIEEE 形式ですが、明確なものは見つかりませんでした。

現在、Visual Source Safe を使用して技術仕様書を保存しています。

実際のドキュメントは MS word で書かれています。

仕様を単語形式で書くことが大きな負担であることがわかった場合、仕様が真に使用されるためには、使用、さらに重要なことにアクセスに障壁があってはなりません。

ドキュメントをすばやくスキャンしたり、他の依存ドキュメントまたはセクションへのハイパーリンクを取得したりできない場合、これらすべてが何の役に立つのでしょうか?

それを背景として：

本当にアクセス可能なドキュメントを作成するために存在するソフトウェアは何ですか? つまり、他のページ/セクションなどへのハイパーリンクですか? またはクエリ可能で、モジュール 4.5.3 に依存するすべてのドキュメントを表示できます

それは基本的にただのWikiですか？他に何か？

私は、多くのテキストと、すべてのビルドに含めることも含めないこともできるさまざまなモジュールを持つアプリケーションを開発しています。

保存されたプロジェクトごとに、すべての詳細 (つまり、そのプロジェクトで使用されているアルゴリズムの説明など) を含むレポートが自動的に生成されます。現在、すべてのテキストを文字列としてソース コードに埋め込み、po および mo ファイルを通じてさまざまな言語もサポートしています。

このシステムの良い点は、ドキュメントとレポート ファイルを動的に生成するのが非常に簡単であることです。悪い点は、ソース コードに大量のテキストがあるのは見苦しく、書式設定 (つまり html を使用) が快適ではないこと、テキストの編集が難しく、簡単なスペル チェックができないこと、翻訳がひどいことです。

最後の質問は、ドキュメントをコードに埋め込むのと、さまざまな言語の外部ドキュメント ファイル (html など) を作成して実行時に解析するのとでは、どちらがよいでしょうか? 明らかに、ソフトウェアのコア テキスト (メッセージ ボックスなど) はコードに残ります。

問題があれば、私は wxWidgets を使用して C++ で作業しています。

Doxygen を使用して、C と x86 アセンブリ言語が混在するレガシー コードを文書化したいと考えています。アセンブリ言語はインラインではなく、個別のアセンブリ専用ファイルにあります。アセンブリ言語部分を文書化するにはどうすればよいですか?

.Net でメンバーをインラインで文書化するにはどうすればよいですか? 説明させてください。コメントからドキュメントを抽出するほとんどのツールは、メンバー宣言の後に簡単な説明を追加できるインライン ドキュメントをサポートしています。何かのようなもの：

C# または .NET 言語でこれを行う方法はありますか?