単体テスト済みのサンプル コード (ソース コード、出力、および任意の入力ファイル) を JavaDoc に挿入するライブラリを作成しており、多くのカスタマイズが可能です。このライブラリを使用する主な方法は、次のようなインライン タグレットを使用することです。
{@.codelet.and.out my.package.AGreatExample}
{@.codelet my.package.AGreatExample}
{@.file.textlet examples\doc-files\an_input_file.txt}
{@.codelet.and.out my.package.AGreatExample%eliminateCommentBlocksAndPackageDecl()}
カスタムタグレット(およびドックレットでさえも) は requireであるためcom.sun、これは Java 自体ほどクロス プラットフォームではないことを意味します。(これが関連しているかどうかはわかりませんが、「javadoc」という単語、および部分文字列「doc」でさえもJava 8 言語仕様にはありません。)
このように制限されたライブラリを作成するという考えは好きではありません。それで、私は何をしますか？これまでの私の考えは、
- 既存の javadoc パーサーを利用するために、私は
com.sunタグレットを使い続けています。ただし、私はこの信頼をcom.sunできる限り「薄い」ものにしています。つまり、taglet クラスに入れるコードはできるだけ少なくし、大部分のコードは に依存しない別の場所に残しますcom.sun。 - 私は、特定のタグレットのみを検索する独自のパーサーの作成に取り組んでいます。これは苦痛ですが、それほどひどいものではありません。を検索しながら、各 Java ソース ファイルの行を反復処理します
\{@\.myTagletName (.*?)\}。com.sunそのテキストをキャプチャすると、タグレット内のコードとほとんど同じになります。 - このパーサーは、javadoc を実行する前に実行する必要があるため、ディレクトリ構造を複製する必要があります。(1) 解析されていないカスタム タグを含む元のコード、(2) 解析された出力を含むそのコードの複製。すべてのコードを重複したディレクトリにコピーし、これらのタグレット (何らかの方法でパーサーに「登録」されているクラス) を持つことがわかっている Java ファイルのみを解析します。
これは合理的なアプローチですか？クロスプラットフォームの javadoc/taglet パーサーがすでにあるので、自分で作成する必要はありませんか? タグレットのようなクロスプラットフォームは既に存在しますか? JavaDoc自体はクロス プラットフォームではありませんか、それともカスタムのタグレットとドックレットだけですか?
この決定 (インライン タグレットを使用するため) により、ライブラリからロックアウトされている人の数を大まかに把握したいのですが、ほとんどの場合、長期的な解決策を探しています。
(上記の Java 8 リンクにもかかわらず、私は Java 7 を使用しています。)
私の元のアイデアよりもエレガントなタグレットの提案については@fgeに、不吉だが役立つcom.sun警告については@Michaelに感謝します。