こんにちはこんばんは。STORES のn-sekiです。

STORSE 決済というサービスのAndroidアプリ/SDKを開発しています。

本記事ではアプリではなく、SDKでの開発トピックを取り上げようと思います！

このSDKは決済 SDKと呼んでいて、モノとしてはAndroidライブラリ（aar）になっており、アプリに組み込んでいただくことでクレジットカードなどのキャッシュレス決済手段をかんたんに導入できます。

coiney.com

ライブラリなので開発者向けにAPIドキュメントも公開しているのですが、もともとJavaで実装されていたこともあり、javadocコマンドを使って生成したドキュメントを公開していました。

少し前にライブラリインタフェースのフルKotlin移行を実施した*1のに併せ、ドキュメント生成ツールをDokkaに移行しました。

今回はこのときの話を書いてみます。

Javadoc

まずJavadocをかんたんに紹介します。

/**
 * Javaのサンプルクラスです
 *
 * @author n-seki
 * @since 1.0.0
 */
public class JavaSample {

   /**
    * サンプルメソッド<br>
    * {@link JavaSample#newFunction()}も参照してください
    *
    * @return 計算結果
    */
   public int sample() {
      return 0;
   }

   public void newFunction() {}
}

上記のように/*で囲った部分にクラス／メソッドの説明文や、@から始まるタグを利用することで形式的なコメントを記述することができます。

そして統一されたルールでコメントを書けるだけではなく、javadocコマンドを使うことでHTML形式のAPIドキュメントを生成できます。

試しに上記サンプルコードに対してjavadocを使うとこのようなドキュメントが生成されます。

今回はこのような単純なコマンドを実行しました。

javadoc -public JavaSample.java

生成されたファイル一式をWeb上で公開すればAPIドキュメントの完成です。

Dokka

DokkaはKotlin向けのAPIドキュメント生成ツールです。

Kotlin向けと謳っておりKDocコメントを解釈できるのはもちろん、上述のJavadocも解釈できるようです。

KDoc

まずKDocを紹介します。KDocはKotlinのドキュメント用言語です。Javadocと同じ立ち位置ですね。

kotlinlang.org

KDocの例をみてみましょう。

/**
 * Kotlinのサンプルクラスです
 *
 * @author n-seki
 * @since 1.0.0
 */
class KotlinSample {

    /**
     * サンプルメソッド<br>
     * [newFunction]も参照してください
     *
     * @return 計算結果
     */
    fun sample(): Int {
        return 0
    }

    fun newFunction() {}
}

Javadocと同様@から始まるタグを使うことができます。全体的にJavadocと似ていますが、記法など異なる部分もあるので詳しくはKDocのドキュメントを参照ください。

kotlinlang.org

Dokkaの導入

AndroidなどのGradleなプロジェクトの場合、gradleファイルで設定を行って、dokkaHtmlなどの定義ずみGradleタスクを実行することでドキュメントが生成できます。

./gradlew dokkaHtml

このタスクだとHTML形式のドキュメントが生成されますが、Dokkaでは他のフォーマットの生成もサポートしています。たとえば、まだAlphaなステータスのようですが、Markdown形式もサポートしているようです。

kotlinlang.org

サポートされているすべての形式やGradleプロジェクトへの導入方法については公式ドキュメントを参照してください（丸投げ）。

kotlinlang.org

Dokkaへ移行！

上述したとおり、決済 SDKはJavaからKotlinへの移行実施中だったので、だいたい以下のような流れで対応しました。

ライブラリをJavaからKotlinに書き換えるときに、一緒にJavadocをKDocに書き換える
- Android Studioの Convert to Kotlin from JavaによってほぼほぼKDocに書き換わるので、必要があれば人の手で微調整
Dokkaをプロジェクトに導入して検証
決済 SDKのリリースに合わせてDokkaで生成したドキュメントを公開！

公式ドキュメントが丁寧だったのでDokkaの導入は悩むこともなく、とてもスムーズでした！

......と言いたいところですが、何事にも予想外のことはあるわけで、2点ほど頭を使うポイントがありました。

つまずいたこと

設定が適用できない

Dokkaではドキュメントにロゴを表示したり、フッターに任意の文字列（コピーライトなど）を表示したりとさまざまなカスタマイズができます。

設定方法は公式ドキュメントに記載されているとおりです。

https://kotlinlang.org/docs/dokka-gradle.html

が、このとおりに実装しても設定が適用されずに困ったぞ......となりました。

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        // 設定
    }
}

改めてドキュメントにあたってみたところSource Set Configurationという章があり、Gradleのソースセットごとに設定が行えるよ、ということが書いてありました。

Gradle | Kotlin Documentation

これを参考に次のように実装したところ、無事に設定が適用されました。

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        named("main") {
            // 設定
        }
    }
}

プロジェクト構成によって異なる部分にはなりますが、同じように設定がうまく適用できない場合にはSource Set Configurationを見直してみると良いかもしれません。

KDocにはDeprecatedタグがない

Javadocには非推奨を表すDeprecatedタグがあり、これが付いていると生成したドキュメントに「非推奨」と表示されます。

しかしKDocには非推奨を表現するタグはなくドキュメントにこのような記述があります。

KDoc does not support the @deprecated tag. Instead, please use the @Deprecated annotation.

というわけで、Deprecatedアノテーションを使う必要があります。

kotlinlang.org

DokkaはDeprecatedアノテーションも見てくれて、これが付いているメソッドやプロパティは「非推奨」とマークされます。アノテーションに渡すmessageもドキュメントに取り込んでくれるため、JavadocのDeprecateタグと同等の情報をドキュメント化できます。

また@DeprecatedアノテーションでReplaceWithも渡してあげると、より親切なドキュメントが生成できます。

@Deprecated(
    message = "v1.1.0から非推奨になりました",
    replaceWith = ReplaceWith(
        expression = "newFunction",
        imports = ["com.example.blogmigrationdokka.KotlinSample"],
    ),
)
fun oldFunction() {}

@Deprecatedアノテーションが付いていると開発時にもAndroid Studioで警告やreplace提案をしてくれるので積極的に利用していきたいですね。