web-dev-qa-db-ja.com

Javadocに代わる最新の優れた方法はありますか?

それに直面しよう:デフォルトJavadocが醜く見えるように設計者である必要はありません。

再スタイルされたJavadocを提供するWeb上のリソースがいくつかあります。ただし、デフォルトの動作は製品を表すものであり、見栄えはかなり良いはずです。

もう1つの問題は、Javadocの使いやすさが他の同様のリソースに比べて最新でないことです。

特に巨大なプロジェクトは、Firefoxのクイック検索を使用してナビゲートするのが困難です。

実用的な質問:
既存のJavadocをブラウザよりも使いやすい方法で閲覧できるスタンドアロン(デスクトップ)アプリケーションはありますか?
Monoのドキュメントブラウザのようなものを考えています。

理論的な質問:
Javadocを何らかの方法で標準化された方法で進化させる計画がある場合、誰か知っていますか?
EDIT:このトピックに関するSunのwikiへの便利なリンク

私は Markdown(Java)Doclet を作成しました。これは、Markdown形式のテキストでソースコメントを取得し、同じHTML Javadocを作成します。

新しいドックレットもテキストのスタイルを変更しますが、生成されたHTMLはこの段階では変更されません。

これは、おそらく現在のJavadocでの最大のユーザビリティの問題であるHTML-in-Java-commentingの問題に対処する方法の1つです。

41
Richard Nichols

Javadocの概念が古くなっているとは思いません。私の知る限り、これらの概念は何年も前にdoxygenという名前の製品に根付いていました。これにも前任者がいます-ドナルド・クヌースがTeXを作成するために使用したプログラミング環境( Literate programming )を見てください。

それでも、プログラムコードとドキュメンテーションの単一のソースを持つことは興味深いアイデアです。

さらに、ドキュメントのプレゼンテーションは、JavaDocツールでサポートされているプラ​​グインシステムを使用して、特別なニーズに合わせてカスタマイズできます。 Web経由で直接アクセスできるデータベースに直接パブリッシュするプラグインを(私たちのように)提供することができます。コラボレーションを使用すると、誰もが元のソースに戻る方法を見つける可能性があるドキュメントに追加のコメントまたは説明を提供できます。

21
Ralf Edmund

Javadocは、私が今まで見た中で最高のソースコード自動ドキュメント生成システムです。その大部分は、とてもシンプルなことです。必要に応じて、5歳の携帯電話でもjavadocを閲覧できます。少し手直しをする必要があることに同意しますが、特にJDKを参照するのは面倒ですが、私たちが現在持っているものは、RESTfulで使いやすいソリューションであるため、ホイールを再発明するつもりはありません。どこでも。

13
Esko

最近、SunがJavadoc HTML出力の最新化に取り組んでいるというメールが転送されました。上記のメールから:

JDK7のjavadoc/docletの改善を提案しています。プロジェクトのWikiページは http://wikis.Sun.com/display/Javadoc/Home にあります。提案された改善の一環として、javadoc出力のUIが刷新されます。新しいデザインのスクリーンショットがプロジェクトのwikiにアップロードされます。 javadoc出力マークアップは、有効なHTMLおよびWCAG 2.0に準拠するように変更されます。

そのため、多少遅れても、確実に作業が進んでいます。しかし、私の目には、Javadocの最大の欠点の1つは、HTMLとの非常に密接な結合です。多くのクラスには、リテラルHTMLを含み、出力がHTMLであることに依存するJavadocがあります。残念ながら、これはいつでも変わることはないと思います。それでも、これは開発者が自由にHTMLに必要なものを自由に含めることができることを意味します。これは無効であるか、整形式ではない、などです。したがって、javadocツールからの出力の調整はこれの一部にすぎず、もう一方はうまくいきません。 tと変更できないため、残ります。

文書の閲覧に関しては、HTML文書も扱いにくいと思います。私は通常、EclipseでJavadocビューを使用します。これには欠点もありますが(遅く、実際に検索することはできません)、ほとんどの場合これで十分です。

11
Joey

あなたの実用的な質問に答えるために、私はグーグルで友達に尋ね、これらを思いつきました。 Forrestdoc、doclet、doxygen。

2つ目の質問ですが、そうです。「Web-oh-twoeye」ではありませんが、少なくともオフライン環境での動作が保証されており、APIと一緒に出荷できるほど小さいです。私はフレームの使用を拒否しますが、javadocではかなりうまく機能します。変更する予定は見たことがありません。 Eclipseは、Javadocの読み取り、解釈、および生成に関する限り、javadocをある程度サポートしています。

5
Gerrie

個人的には、私はまだJavadocがとても便利だと思っています。特に標準化されているため。ナビゲートしやすい主要なドキュメントスタイルは知りません(非常に主観的かもしれませんが、個人的には、MSDNを使用するのは恐ろしいと思います)。

検索: Javadoc Search Frame を使用すると、あらゆる種類のJavadocがはるかに使いやすくなります。 Firefoxのユーザースクリプト および Google Chrome Extension として利用できます。

5
Joachim Sauer

あなたはそれをあまり積極的ではなく、圧倒的な方法で言いたいかもしれません。ほとんどの人は技術的なリソースがどのように見えるか気にしません、そして「それは十分なWeb 2.0ではありません!」むなしいmarketroidspeakのように聞こえます。

そして、あなたは「より使いやすい」と正確に何を考えますか?個人的に、私は間違いなく全文検索とより使いやすいブラウザを望んでおり、AJAXはそれらを助ける可能性があります。

さて、JavaDocの良い点は、古くなったものとは正反対であり、任意に拡張できることです。先に進んで、必要な種類のAPIドキュメントを生成する doclet を書いてみませんか?

他の誰もこれまでこれを行っていないのはなぜですか(これは明らかにそうです)は誰もが推測していることです。

3

DocBookドックレットがあります。 DocBookは(X)HTMLよりも豊富なドキュメントタイプであり、技術的なコンテンツの記述に適しています。 DocBookソースから、あらゆる種類の異なる出力フォーマットを生成できます。

2
Nat

個人的には、HTML(したがってタグを扱いやすい)JavaDocよりも読みやすい「コメントドキュメント」標準が欲しいです。

たとえば、ここで使用されているMarkDownは、ソースで人間が読める優れた形式で、ソースの外部で適切にフォーマットされています。

現在のJavaDocでは、多くの人がJavaDocコメントを使用していると思いますが、実際には可能な範囲で文書化しません。誰もが、ドキュメント化されていないかほとんどドキュメント化されていないAPIのオンラインJavaDocを閲覧したため、本来の使い方よりはるかに使いにくいと思います。

これは、JavaDocコメント(たとえば、項目のリスト)内に入れた可能性のある読み取り可能な構造を1つの大きなテキストの塊に完全に破壊するコード再フォーマッタ(Eclipse内、またはソースコミット時など)には役立ちません。文字通り2つのキャリッジリターンを使用したい場合を除き(1つを使用したい場合)。

2
JeeBee

どういうわけか標準化された方法でJavadocを進化させる計画がある場合、誰かが知っていますか?

Javadocへの拡張を指定する対応するJSR(JSR 260)は、JDK 7から投票されました(現時点では)。計画されたものの概要(- このサイト から):

Javadocをアップグレードして、より豊富なタグのセットを提供し、Javadocドキュメントのより構造化されたプレゼンテーションを可能にします。このJSRは、メソッドとフィールドの分類、クラスとパッケージのセマンティックインデックス、静的、ファクトリ、非推奨メソッドと通常のメソッドの区別、プロパティアクセサーの区別、情報の結合とビューへの分割、例と一般的なユースケースの埋め込みをカバーしています。もっと。

JDK 7の全体的な見通しは かなり厳しい です。

2
pmf

標準ドックレットをカスタムドックレットに置き換えて、プロジェクト固有のニーズを満たすものを提供できるため、JavaDoc自体は非常に柔軟性があります。

私が取り組んでいるプロジェクトでは、JavaDocが完全に統合された製品用に、HTML/XMLベースのドキュメントシステム(JSでクライアント側のXSLT 2.0を使用)を作成しました。このため、カスタムドックレットを使用してXMLでJavaDocデータを生成しました。これは、タグコメントを使用して、コードコメント内のHTMLマークアップも適切に形成されるようにしました。

これにより、シングルページアプリ(デスクトップツールと同様)を使用してインタラクティブなユーザーエクスペリエンスを提供できましたが、サーバー側のコードやインフラストラクチャなしで、すべてブラウザー内から実行できました。ビューアには、検索、ツリーナビゲーションなどの標準機能が含まれていました。

これは、かなり広大なドキュメントのサンプルエントリポイントへのリンクです。 JavaDocビューアサンプル

ここにも画像があります: enter image description here

1
pgfearo

スマートな検索可能なjavadocビューア:

私は何度も、JavaDocを閲覧する問題に直面しています。 Adnroid doc検索オプションのようなものを探していました。やっとそのようなものを手に入れました。 Firefoxを使用している場合の解決策はこちらです。

  1. プラグインGreaseMonkeyをインストールします。これは、私たちが目にする方法でカスタマイズするWebページです。 (Java docページをカスタマイズする必要があるため、クラス名で検索できます) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey /

  2. Greasemonkeyを機能させるには、カスタマイズ用のユーザースクリプトが必要です。これはgreasemonkeyによって自動的にダウンロードできます。 JavaDoc search frame または JavaDoc incremental search からユーザースクリプトをインストールします。

これは私にとってはうまくいきます。

0
karim