Javadoc：static 最终枚举参考的文档值

Question

Let's say I have:

public enum Color {
    RED,
    GREEN,
    YELLOW
}

Then elsewhere in my code I have

public static final Color DEFAULT_COLOR = Color.RED;

Now I would like to document to readers of my Javadoc what the value of DEFAULT_COLOR is (of course without repeating myself). How to do that?

The problem being - as I see it - that such reference (although declared static final and pointing to an enum) will not show up in Javadoc's "constant-values.html". I see no technical reason why it shouldn't but as far as I can tell it doesn't. Perhaps I've simply misunderstood?

Refinement

To be precise the question is about static final declarations of an Enum variable where the right-hand-side is a single identifier as defined by the JLS, thus excluding cases where the RHS is a more complex expression. This is similar to the current Javadoc behavior for assignments of primitive types where Javadoc will not try to render if the RHS isn't a so-called 'constant expression'. We can surely expect Javadoc to do the same can-I-render-this-unambigiusly? analysis for Enums, no?. By saying the RHS must be a single identifier we limit ourselves to something which - IMO - should be unambiguously renderable for Javadoc.

Answer 1

As a comment already said, only if the value is a compile time constant does javadoc render it (and very few things are - true , false , number literals, string constants is where it starts. Operators where all operands are constants are also constant. Then any static final field that is initialized with such a constant is itself constant. Thus, static final int foo = SOME_OTHER_FIELD + YET_ANOTHER + 5; can be constant.

That means Color.RED isn't a constant and thus isn't shown.

It's not just a matter of 'resolving things', it's a matter of rendering.

Imagine you wrote this:

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

should the entire list be injected into the javadoc? Hopefully this example makes it clear that the answer isn't always 'yes', and it is not really feasible to draw a line.

Even if the answer is yes, how do you propose the javadoc renders this information? Just take the raw source code and dump it straight into the html? Take the raw source code, and auto-reformat it? What other options exist?

Javadoc can't assume it can resolve the expression. Imagine the expression is:

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

That should make it clear that you have no feasible options to render non-CTCs in any way other than to show either the source with some level of cleanup applied, or nothing at all.

What you'd presumably want to see instead is either:

• That the JVM spec gains the ability to treat enums as compile time constants (there is a marked difference; at the class level, constants are just stored verbatim, with their actual value, in the class file, whereas non-CTCs aren't stored; instead a static {} block is generated that generates these. For example, public static final long STAMP = System.currentTimeMillis(); is turned into a class file that has a static init 'method' that runs that code - you can't reduce that to a constan). That's rather a big update to all of java just for the benefit of javadoc, which is weird.
• That the javadoc tool parts ways with the JVM spec and goes its own way on CTC. This seems annoying. Surely you'd want public static final Color DEFAULT_COLOR = SomeOtherClass.DEFAULT_COLOR; to work just as well (it does if those were ints,), so that makes javadoc complicated and inconsistent. Just not worth it.
• An option to tell javadoc to just take the source code of the initializer and render it verbatim (or with a light application of reformatting, perhaps) into the HTML.

That third one seems fair, something like:

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

but javadoc simply does not work that way.

Okay, so how do I do this without repeating myself?

You can't. Sorry about that.