プロジェクトドキュメント用のJavadoc

Question

私が取り組んでいるJavaプロジェクトを文書化したいと思います。これまで、私は典型的には、Wikiの設計とソフトウェアAPIを文書化しました。しかし、最近、模擬テストにMockitoを使用した後、私は実際のjavadocsのプロジェクトレベルのドキュメントの量と品質に感心しました。

私の質問は、プロジェクトの上位レベルのビュー（アーキテクチャーや設計上の決定など）を文書化するためにJavadocを使用するのが一般的であるのか、それともwikiに最もよく記述されているのですか？

Answer 1

あなたの聴衆が誰であるかによって異なります。

視聴者が主にAPIを使用する場合は、Javadocに明確な簡潔な説明（例を含む）を投資する方が一般的です。オーディエンスにAPIが見えない可能性が高い場合は、Javadocの外部でドキュメントを管理する方がよいでしょう。これは、ドキュメンテーションのナビゲート方法の主要な機能です。 Javadocナビゲーションはプログラミングプロセスを容易にします。

ドキュメントをwikiに入れるか、PDFにするかは、オーディエンスによって異なります。 wikiのための唯一の理由がドキュメントのHTML表現に直面するならば、Docbookに似たようなものを使用すれば、同じドキュメンテーションのPDF表現を生成するという追加の利点が得られます。あなたが本当に活発なコミュニティを持っているなら、Wikiは近所の人にあなたのドキュメントを変更させる能力に輝きます。

製品の強みがニーズに合っているかどうかを判断し、そうであれば正しい選択です。

Answer 2

Javadocは、APIレベルのドキュメントを生成するのに最適です。私は高レベルのドキュメントのためにwikiを使用しています。私はconfluenceを私のwikiとして使用しており、建築図に使用できるいくつかのプラグインがあります。