maven-javadoc-pluginのbuild時、javadocのoptionをアレコレ指定する方法

java Java
maven Maven

前提

環境はMac
プロジェクトをMavenで管理しており、すでにmaven-javadoc-pluginが導入されていること。

pom.xml

<project>
    …
        <build>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>2.10.4</version>
                    <configuration>
                        <quiet>true</quiet>
                    </configuration>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals>
                                <goal>jar</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    …
<project>

Option一覧

そもそもjavadocにはどのようなoptionがあるのだろう?

$ javadoc -help

使用方法: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview <file>          HTMLファイルから概要ドキュメントを読み込む
  -public                   publicクラスとメンバーのみを示す
  -protected                protected/publicクラスとメンバーを示す(デフォルト)
  -package                  package/protected/publicクラスとメンバーを示す
  -private                  すべてのクラスとメンバーを示す
  -help                     コマンド行オプションを表示して終了する
  -doclet <class>           代替docletを介して出力を生成する
  -docletpath <path>        docletクラス・ファイルを探す場所を指定する
  -sourcepath <pathlist>    ソース・ファイルのある場所を指定する
  -classpath <pathlist>     ユーザー・クラス・ファイルのある場所を指定する
  -cp <pathlist>                   ユーザー・クラス・ファイルのある場所を指定する
  -exclude <pkglist>        除外するパッケージ・リストを指定する
  -subpackages <subpkglist> 再帰的にロードするサブパッケージを指定する
  -breakiterator            BreakIteratorで最初の文を計算する
  -bootclasspath <pathlist> ブートストラップ・クラス・ローダーによりロードされた
                                   クラス・ファイルの場所をオーバーライドする
  -source <release>         指定されたリリースとソースの互換性を提供する
  -extdirs <dirlist>        インストールされた拡張機能の場所をオーバーライドする
  -verbose                  Javadocの動作についてメッセージを出力する
  -locale <name>            en_USやen_US_WINなどの使用するロケール
  -encoding <name>          ソース・ファイルのエンコーディング名
  -quiet                    状態メッセージを表示しない
  -J<flag>                  <flag>を実行時システムに直接渡す
  -X                        非標準オプションの概要を出力し終了する

標準のdocletにより提供されるもの:
  -d <directory>                    出力ファイルの転送先ディレクトリ
  -use                              クラスとパッケージの使用ページを作成する
  -version                          @versionパラグラフを含める
  -author                           @authorパラグラフを含める
  -docfilessubdirs                  doc-fileサブディレクトリを再帰的にコピーする
  -splitindex                       1字ごとに1ファイルに索引を分割する
  -windowtitle <text>               ドキュメント用のブラウザ・ウィンドウ・タイトル
  -doctitle <html-code>             概要ページにタイトルを含める
  -header <html-code>               各ページにヘッダーを含める
  -footer <html-code>               各ページにフッターを含める
  -top    <html-code>               各ページに上部テキストを含める
  -bottom <html-code>               各ページに下部テキストを含める
  -link <url>                       <url>にjavadoc出力へのリンクを作成する
  -linkoffline <url> <url2>         <url2>にあるパッケージ・リストを使用して<url>のdocsにリンクする
  -excludedocfilessubdir <name1>:.. 指定された名前のdoc-filesサブディレクトリをすべて除外する
  -group <name> <p1>:<p2>..         指定するパッケージを概要ページにおいてグループ化する
  -nocomment                        記述およびタグを抑制して宣言のみを生成する
  -nodeprecated                     @deprecated情報を除外する
  -noqualifier <name1>:<name2>:...  出力から修飾子のリストを除外する
  -nosince                          @since情報を除外する
  -notimestamp                      非表示のタイムスタンプを除外する
  -nodeprecatedlist                 非推奨のリストを生成しない
  -notree                           クラス階層を生成しない
  -noindex                          索引を生成しない
  -nohelp                           ヘルプ・リンクを生成しない
  -nonavbar                         ナビゲーション・バーを生成しない
  -serialwarn                       @serialタグに関する警告を生成する
  -tag <name>:<locations>:<header>  単一の引数を持つカスタム・タグを指定する
  -taglet                           タグレットの完全修飾名を登録する
  -tagletpath                       タグレットのパス
  -charset <charset>                生成されるドキュメントのクロスプラットフォームでの文字エンコーディング
  -helpfile <file>                  ヘルプ・リンクのリンク先ファイルを含める
  -linksource                       HTML形式でソースを生成する
  -sourcetab <tab length>           ソース内のタブの空白文字の数を指定する
  -keywords                         HTMLのmetaタグに、パッケージ、クラスおよびメンバーの情報を含める
  -stylesheetfile <path>            生成されたドキュメントのスタイル変更用ファイル
  -docencoding <name>               出力の文字エンコーディングを指定する  



かなりいっぱいありますね(笑)
下記でいくつか抜粋して実際に実行してみます。

実際にoptionを指定して実行してみる

1.上記一覧の-d <directory>に対応するタグ<outputDirectory>を使って、出力するディレクトリを指定してみる

pom.xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.4</version>
            <configuration>
                <quiet>true</quiet>
                <outputDirectory>javadoc/report</outputDirectory>  <!-- ここに記述を追加 -->
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build

対象プロジェクトのディレクトリに移動し下記コマンドを実行

$ mvn install

対象プロジェクト/javadoc/reportにファイルが出力されているのか確認する

$ ls -l

allclasses-frame.html
allclasses-noframe.html
com
constant-values.html
deprecated-list.html
help-doc.html
index-all.html
index.html
overview-frame.html
overview-summary.html
overview-tree.html
package-list
script.js
serialized-form.html
stylesheet.css

ちゃんと出てる!

2.Option一覧の-bottomに対応するタグ<bottom>を使って、出力されるレポートのコピーライトを任意の文字として出力する

pom.xml

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.4</version>
            <configuration>
                <quiet>true</quiet>
                <bottom><![CDATA[<p class="legalCopy"><small>Copyright &#169; 2016. test-framework.</small></p>]]></bottom>  <!-- ここに記述を追加 -->
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

対象プロジェクトのディレクトリに移動し下記コマンドを実行

$ mvn install

対象プロジェクト/javadoc/report/serialized-form.htmlにファイルが出力されているのか確認する

$ cat serialized-form.html

<!-- ======== END OF BOTTOM NAVBAR ======= -->
<p class="legalCopy"><small><p class="legalCopy"><small>Copyright &#169; 2016. test-framework.</small></p></small></p>
</body>
</html>

END OF BOTTOM NAVBARの下にちゃんとコードが反映されている


ブラウザでも確認
スクリーンショット 2016-07-25 12.42.31.png



コピーライトが出力されてる!OK


まとめ

基本的に<configuration>の中に定義をしていく、他のoptionも同じノリで追加できる。
最初にoption指定のコマンド実行で、どういうことをしてくれるのか色々試した後にpom.xmlへ設定の定義を追加すると良さそう!
コマンド実行の方が楽にできるので!
二通りしか紹介できてないので、今後追加していく予定です。

参考

http://maven.apache.org/plugins-archives/maven-javadoc-plugin-2.10.3/
https://maven.apache.org/plugins/maven-javadoc-plugin/usage.html