AndroidのJavaDocをgradleで生成する
Android Studioの設定でもできるけどbuild.gradleでやったほうが便利かなと。
最近Android StudioでAndroidアプリを作っているんだけども、JavaDocを生成するのはどうするんだろうと調べてみたら、以下が見つかった。
たしかに、これで生成はできたのだけれども、どうせならbuild.gradleで定義してAndroid Studioがない環境でも実行できたらいいなと。
環境
OS | Windows 8.1(x64) |
JDK | 1.8.0(64bit) |
Android Studio | 1.2.1.1 |
Android Gradle plugin | 1.2.3 |
Gradle | 2.2.1 |
調べてみた
で調べてみたらJavaプラグインだと、Javadocタスクをそのまま使えるようなんだけど、Androidプラグイン*1の場合は、普通にJavadocタスクを定義してもclasspathに指定するjavadocコマンドの引数に設定するクラスパス情報(javaCompile.classpath.files)が取れない(自分には取り方が分からない)ので、困ったけど、以下のブログのやり方で生成できることがわかった。
作ってみた
上記ブログのコードをベースに自分なりに改良したのがこちら。
project.ext { if (android.hasProperty('applicationVariants')) { androidVariants = android.applicationVariants }else if (android.hasProperty('libraryVariants')) { androidVariants = android.libraryVariants } } project.androidVariants.all { variant -> task("javadoc", type: Javadoc, overwrite: true) { title = "XXXXXXX" source = variant.javaCompile.source ext.androidJar = "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar" classpath = files(variant.javaCompile.classpath.files) + files(ext.androidJar) options { links("http://docs.oracle.com/javase/jp/7/api/"); linksOffline("http://d.android.com/reference", "${android.sdkDirectory}/docs/reference") setMemberLevel(JavadocMemberLevel.PUBLIC) docEncoding = 'UTF-8' encoding = 'UTF-8' charSet = 'UTF-8' } exclude '**/BuildConfig.java' exclude '**/R.java' } }
で以下のようにタスク名を指定して実行すると生成される。
$ gradlew javadoc :xxxxx:javadoc BUILD SUCCESSFUL Total time: 13.086 secs $ ls xxxxx/build/docs/javadoc/ allclasses-frame.html index-all.html overview-tree.html allclasses-noframe.html index.html package-list constant-values.html jp script.js deprecated-list.html overview-frame.html serialized-form.html help-doc.html overview-summary.html stylesheet.css
変更点は以下の通り
アプリでもライブラリでも共通の定義で動くようにした(つもり)
参考にしたブログだと「android.libraryVariants」を使っていたり「android.applicationValiants」を使っていたりまちまち。これはモジュールがアプリかライブラリなのかによって参照するプロパティ名が異なる為。
プラグイン | 参照プロパティ |
com.android.application | android.applicationValiants |
com.android.library | android.libraryVariants |
それぞれのVariantsのプロパティとして参照できる値は以下の「Manipulating tasks」の辺りに書いてある。
で、それに合わせてbuild.gradleに記述するときに以下のように一文を変更すればいいんだけど、忘れっぽいのでそこは自動判定するようにしてみた。
- アプリケーションモジュールの場合
android.applicationValiants.all { variant -> task("javadoc", type: Javadoc) { … } }
- ライブラリモジュールの場合
android.libraryVariants.all { variant -> task("javadoc", type: Javadoc) { … } }
- どっちでも動くように判別
project.ext { if (android.hasProperty('applicationVariants')) { androidVariants = android.applicationVariants }else if (android.hasProperty('libraryVariants')) { androidVariants = android.libraryVariants } } project.androidVariants.all { variant -> task("javadoc", type: Javadoc) { … } }
プロジェクト内にアプリケーションモジュールとライブラリモジュールがある構成で、それぞれのモジュールのbuild.gradleに上記設定を定義してタスク実行したところ、両方共にJavaDocが生成されていることは確認した。それぞれにしかない独自のプロパティを参照することにならなければ、これで大丈夫なのかなと。
外部JavaDocへのリンク設定を変更
JavaSDKのURL指定を日本語ページに変更。AndroidSDKのリンクはlinksだとJavadoc生成時に「URL取出しエラー: http://d.android.com/reference」という警告がでて上手くリンクが作成されないので、linksOfflineに変更。第2引数にローカルのAndroidSDKのパスが指定されているけど、その場所にAPIドキュメントが存在しなくても第1引数を参照するJavaDocが生成される。
エンコーディングとか出力レベルとか
ソースコードがUTF-8でもエラーがでないような設定に。その他、Javadoc関連のオプションについては、以下のリンクを参照
- JavaDocタスクのプロパティは以下の「23.8. Javadoc」を参照
- JavaDocタスクのoptionsプロパティの詳細はこちらを参照
CoreJavadocOptions (Gradle API 2.2-20140924021627+0000)
StandardJavadocDocletOptions (Gradle API 2.2-20140924021627+0000)
ついで
あと、以下のプラグインも併用すればJavaSDKさえ導入してあればどこでもビルドとJavaDoc生成ができるので便利なことこの上なし。
- この本は結構オススメ
エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方
- 作者: 佐藤竜一
- 出版社/メーカー: 翔泳社
- 発売日: 2009/06/30
- メディア: 単行本(ソフトカバー)
- 購入: 15人 クリック: 263回
- この商品を含むブログ (49件) を見る
*1:「com.android.application」と「com.android.library」を合わせてそう呼んでみた