如何自动将枚举的字段值属性整合到其JavaDoc中？

给定这样一个枚举类：

public enum Planet {
    MERCURY (3.303e+23, 2.4397e6),
    VENUS   (4.869e+24, 6.0518e6),
    EARTH   (5.976e+24, 6.37814e6),
    MARS    (6.421e+23, 3.3972e6),
    JUPITER (1.9e+27,   7.1492e7),
    SATURN  (5.688e+26, 6.0268e7),
    URANUS  (8.686e+25, 2.5559e7),
    NEPTUNE (1.024e+26, 2.4746e7);

    private final double mass;   // in kilograms
    private final double radius; // in meters

    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
    }
}

我们希望MERCURY这类枚举常量的JavaDoc能自动展示对应的字段值（比如3.303e+23和2.4397e6），还能通过类似下面的模板实现字段值自动填充：

Defines the enum with mass {$mass} and radius {$radius}.

下面是几种可行的实现方式：

方式一：自定义JavaDoc Doclet #

Java自带的javadoc工具支持自定义Doclet，我们可以通过编写自己的Doclet来解析枚举常量的字段值，替换模板占位符生成动态JavaDoc。

核心逻辑是：

• 遍历目标枚举类的所有常量
• 用反射拿到每个常量的mass和radius字段值
• 读取预设模板，把{$mass}、{$radius}替换成实际值
• 将生成好的内容作为枚举常量的JavaDoc输出

简化的示例代码（伪代码）：

public class EnumFieldDoclet extends StandardDoclet {
    @Override
    public boolean start(RootDoc root) {
        for (ClassDoc classDoc : root.classes()) {
            if (classDoc.isEnum()) {
                Class<?> enumClass = classDoc.klass();
                for (FieldDoc enumConstant : classDoc.enumConstants()) {
                    // 获取枚举实例并反射读取字段值
                    Enum<?> enumInstance = Enum.valueOf((Class<Enum>) enumClass, enumConstant.name());
                    Field massField = enumClass.getDeclaredField("mass");
                    massField.setAccessible(true);
                    double mass = (double) massField.get(enumInstance);
                    
                    Field radiusField = enumClass.getDeclaredField("radius");
                    radiusField.setAccessible(true);
                    double radius = (double) radiusField.get(enumInstance);

                    // 替换模板生成JavaDoc内容
                    String template = "Defines the enum with mass {$mass} and radius {$radius}.";
                    String docContent = template.replace("{$mass}", String.valueOf(mass))
                                               .replace("{$radius}", String.valueOf(radius));
                    // 后续通过Doclet API将docContent设置为该枚举常量的文档
                }
            }
        }
        return super.start(root);
    }
}

使用时，通过javadoc命令指定这个自定义Doclet：

javadoc -doclet com.yourpackage.EnumFieldDoclet -docletpath /path/to/your/doclet/classes your.package.Planet

方式二：编译时注解处理器 #

可以编写注解处理器，在编译阶段自动为枚举常量生成包含字段值的JavaDoc注释。

具体步骤：

1. 定义一个自定义注解，比如@EnumDocTemplate，用来指定模板内容
2. 编写注解处理器，扫描带有该注解的枚举类
3. 解析每个枚举常量的构造参数或字段值，替换模板里的占位符
4. 自动把填充后的内容生成到枚举常量的JavaDoc中

示例注解定义：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
public @interface EnumDocTemplate {
    String value();
}

给Planet枚举加上这个注解：

@EnumDocTemplate("Defines the enum with mass {$mass} and radius {$radius}.")
public enum Planet {
    // ... 枚举常量
}

编译时，注解处理器会自动把每个枚举常量的JavaDoc替换成填充后的内容，比如MERCURY的JavaDoc最终会变成：Defines the enum with mass 3.303e+23 and radius 2.4397e6.

方式三：IDE代码模板（简单场景） #

如果不想写复杂的工具，也可以利用IDE的代码模板功能，在创建枚举常量时自动同步字段值到注释里。比如在IntelliJ IDEA中：

• 定义枚举常量的代码模板，把构造参数和注释占位符绑定
• 输入模板时，只需填入参数值，注释会自动同步

示例模板：

${ENUM_CONSTANT} (${MASS}, ${RADIUS}) /** Defines the enum with mass ${MASS} and radius ${RADIUS}. */,

这样每次添加新的枚举常量时，注释里的字段值会和构造参数保持一致。

内容的提问来源于stack exchange，提问作者Christian Fries