Lombokで生成したメソッドをJavaDocに反映する方法

Lombok を公開するライブラリとして使用したとき、デフォルトではJavaDocに反映されないため、その手順を紹介します。

大まかな手順としては、Delombok により静的なソースを生成し、そのソースに対してJavaDocを作成するというものです。

Delombokとは？

Lombokによりコンパイル時にAST（Abstract Syntax Tree: 抽象構文木）の構造を動的に変更します。

Delombokはその逆で、動的にメソッドなどを追加するのではなく静的に変更したソースを出力する機能です。

pom.xmlの設定

Delombokのプラグインを追加します。

JavaDocのプラグインには、で、生成されたソースを参照するに指定します。

それぞれ、テスト用ソースに対しても設定します。

<project>
    <build>
        <plugins>
            <!-- Delombokによるソースを出力します -->
            <plugin>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-maven-plugin</artifactId>
                <version>1.18.12.0</version>
                <executions>
                    <!-- 通常のソースに対して生成します -->
                    <execution>
                        <id>delombok</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>delombok</goal>
                        </goals>
                        <configuration>
                            <addOutputDirectory>false</addOutputDirectory>
                            <sourceDirectory>src/main/java</sourceDirectory>
                            <encoding>${source.encode}</encoding>
                        </configuration>
                    </execution>
                    <!-- テスト用ソースに対して生成します -->
                    <execution>
                        <id>test-delombok</id>
                        <phase>generate-test-sources</phase>
                        <goals>
                            <goal>testDelombok</goal>
                        </goals>
                        <configuration>
                            <addOutputDirectory>false</addOutputDirectory>
                            <sourceDirectory>src/test/java</sourceDirectory>
                            <encoding>${source.encode}</encoding>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
    
    <reporting>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
                <version>3.2.0</version>
                <reportSets>
                    <!-- Delombokにより生成したソースに対してJavaDocを生成します -->
                    <reportSet>
                        <id>html</id>
                        <configuration>
                            <sourcepath>target/generated-sources/delombok</sourcepath>
                        </configuration>
                        <reports>
                            <report>javadoc</report>
                        </reports>
                    </reportSet>
                    <reportSet>
                        <id>test-html</id>
                        <configuration>
                            <show>private</show>
                            <sourcepath>target/generated-test-sources/delombok</sourcepath>
                        </configuration>
                        <reports>
                            <report>test-javadoc</report>
                        </reports>
                    </reportSet>
                </reportSets>
            </plugin>
        </plugins>
    </reporting>
</project>

Delombokを使う際の注意事項

Delombokによる生成されたソースについて注意事項として、無駄な空行が入ってしまったり、逆に空行がなくなったっりします。

JavaDocを生成する差には空行は関係ないので気にはしなくてもよいと思います。

Delombok前のソース

package com.github.mygreen.sqltemplate;

import lombok.Getter;
import lombok.NonNull;

/**
 * SQLテンプレートのパラメータをJavaBean として渡すときのSQLコンテキスト。
 * SQLテンプレート中では、JavaBeanのプロパティ名で参照できます。
 *
 *
 */
public class BeanPropertySqlContext extends SqlContext {

    /**
     * JavaBeanのインスタンス。
     */
    @Getter
    private final Object value;

}

Delombokにより生成したソース

// Generated by delombok at Sun Jul 26 23:32:11 JST 2020
package com.github.mygreen.sqltemplate;

/**
 * SQLテンプレートのパラメータをJavaBean として渡すときのSQLコンテキスト。

 * SQLテンプレート中では、JavaBeanのプロパティ名で参照できます。

 *

 *

 */
public class BeanPropertySqlContext extends SqlContext {
    /**
     * JavaBeanのインスタンス。
     */
    private final Object value;

    /**
     * JavaBeanを指定するコンストラクタ。

     * @param object SQLテンプレート中のパラメータとして渡すJavaBeanのインスタンス
     */
    public BeanPropertySqlContext(@NonNull final Object object) {
        super();
        if (object == null) {
            throw new java.lang.NullPointerException("object is marked non-null but is null");
        }
        this.value = object;
    }

    /**
     * JavaBeanのインスタンス。
     */
    @java.lang.SuppressWarnings("all")
    @lombok.Generated
    public Object getValue() {
        return this.value;
    }
}

タツノオトシゴのブログ

主にJavaに関するものです。