Javadoc:静态最终枚举引用的文档值



假设我有:

public enum Color {
RED,
GREEN,
YELLOW
}

然后在我代码的其他地方我有

public static final Color DEFAULT_COLOR = Color.RED;

现在,我想向我的Javadoc的读者记录DEFAULT_COLOR的价值(当然,我不重复(。如何做到这一点?

在我看来,问题是这样的引用(尽管声明为static final并指向枚举(将而不是显示在Javadoc的";常数值.html";。我看不出它不应该这样做的技术原因,但据我所知,它不是。也许我只是误解了?

精炼

确切地说,问题是关于枚举变量的static final声明,其中右手边是JLS定义的单个标识符,因此排除了RHS是更复杂的表达式的情况。这类似于当前Javadoc对基元类型赋值的行为,如果RHS不是所谓的"常量表达式",Javadoc将不会尝试渲染基元类型。我们当然可以期待Javadoc也能做同样的事情?枚举分析,否?。通过说RHS必须是一个单一的标识符,我们将自己限制在一些东西上——IMO——应该明确地为Javadoc呈现。

如前所述,只有当该值是编译时常数时,javadoc才会呈现它(很少有东西是truefalse、数字文字,字符串常数是它的起点。所有操作数都是常数的运算符也是常数。然后,任何用这样的常数初始化的静态最终字段本身都是常数。因此,static final int foo = SOME_OTHER_FIELD + YET_ANOTHER + 5;可以是常数。

这意味着颜色。RED不是常数,因此不会显示。

这不仅仅是一个"解决问题"的问题,也是一个渲染的问题。

想象一下,你写的是:

private static final List<String> COUNTRIES = List.of(... all 300-or-so countries here_);

是否应该将整个列表注入javadoc?希望这个例子能清楚地表明,答案并不总是"是",划清界限也不太可行。

即使答案是肯定的,您建议javadoc如何呈现这些信息?只需获取原始源代码并将其直接转储到html中?获取原始源代码,并自动重新格式化它?还有哪些其他选择?

Javadoc不能认为它可以解析表达式。想象一下表达式是:

public static final Color DEFAULT_COLOR = Math.random() > 0.5 ? Color.RED : Color.BLUE;

这应该清楚地表明,除了显示应用了某种级别的清理的源,或者什么都不显示之外,您没有任何可行的选项来渲染非CTC。

你可能想看到的是:

  • JVM规范获得了将枚举视为编译时常数的能力(有一个明显的区别;在类级别,常量只是与它们的实际值逐字逐句地存储在类文件中,而非CTC则不存储;相反,会生成一个生成这些常量的static {}块。例如,public static final long STAMP = System.currentTimeMillis();被转换为一个类文件,该文件有一个运行该代码的静态init"方法"-你不能将其简化为常量(。这是对所有java的一个相当大的更新,只是为了javadoc的好处,这很奇怪
  • javadoc工具与JVM规范分道扬镳,在CTC上走自己的路。这看起来很烦人。当然,您希望public static final Color DEFAULT_COLOR = SomeOtherClass.DEFAULT_COLOR;也能很好地工作(如果是int,它也能工作!(,因此javadoc变得复杂且不一致。只是不值得
  • 一个选项,告诉javadoc只获取初始值设定项的源代码,并将其逐字逐句地呈现到HTML中(或者使用轻松的重新格式化应用程序(

第三个似乎很公平,有点像:

/** {@showDefault} */
public static final Color DEFAULT_COLOR = Color.RED;

但是javadoc根本不能以这种方式工作。

好吧,那么我该如何做到这一点而不重复自己呢

你不能。很抱歉。

最新更新