読者です 読者をやめる 読者になる 読者になる

初老のボケ防止日記

おっさんのひとりごとだから気にしないようにな。

スポンサーリンク

AndroidのJavaDocをgradleで生成する



Android Studioの設定でもできるけどbuild.gradleでやったほうが便利かなと。

最近Android StudioでAndroidアプリを作っているんだけども、JavaDocを生成するのはどうするんだろうと調べてみたら、以下が見つかった。

qiita.com

たしかに、これで生成はできたのだけれども、どうせなら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)が取れない(自分には取り方が分からない)ので、困ったけど、以下のブログのやり方で生成できることがわかった。

horie1024.hatenablog.com
wiebe-elsinga.com

作ってみた

上記ブログのコードをベースに自分なりに改良したのがこちら。

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」の辺りに書いてある。

tools.android.com

で、それに合わせて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」を参照

第23章 Javaプラグイン

  • JavaDocタスクのoptionsプロパティの詳細はこちらを参照

CoreJavadocOptions (Gradle API 2.2-20140924021627+0000)
StandardJavadocDocletOptions (Gradle API 2.2-20140924021627+0000)

ついで

あと、以下のプラグインも併用すればJavaSDKさえ導入してあればどこでもビルドとJavaDoc生成ができるので便利なことこの上なし。

github.com

qiita.com

  • この本は結構オススメ

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方

*1:「com.android.application」と「com.android.library」を合わせてそう呼んでみた

スポンサーリンク