8

I have a very specific problem about the method java.lang.Enum.values().

I would like to override its javadoc. Very precisely, the current javadoc for this is, after I created my own enum:

public static MyClass.MyEnum[] values()

  ... 
  This method may be used to iterate over the constants as follows:

    for (MyClass.MyEnum c : MyClass.MyEnum.values())
    System.out.println(c);

  Returns:
    ...

But in my company System.out calls are considered bad practice so I would like it not to be shown. My first try was to override values() but it is apparently not possible. Is there another way I can do this? Or is the only possibility to update the generated doc ?

I am also curious about why values() is not overridable. I read on other questions that "it is generated by the compiler". But can someone be more precise? It seems that it's generated from the enum's name, but it does not explain why.

Vince
  • 1,570
  • 3
  • 27
  • 48
  • If you read something on another question, it'd be nice to link to that. Maybe that question needs clarification as well or maybe other people who find your question are interested in that other one as well. – Joachim Sauer Nov 12 '12 at 13:52
  • @JoachimSauer thanks for reporting it, I updated with related question saying it is generated by the compiler. Another post just says you can't override valueOf()/values(): http://stackoverflow.com/questions/9662170/java-override-valueof-and-tostring-in-enum – Vince Nov 12 '12 at 13:59
  • Still did not understand your problem. Why would you want to override values() ? – giorashc Nov 12 '12 at 14:12
  • I want to override values() javadoc. I suppose that for overriding the javadoc, I need to override the method, or at least its declaration. But maybe I'm wrong, please update the question or tell me how to update in this case. – Vince Nov 12 '12 at 14:16
  • @Vince: personally I think your best bet (in the short and medium run) is to post-process the generated Javadoc to contain the content you want in the code sample. – Joachim Sauer Nov 12 '12 at 14:18
  • @JoachimSauer I'm afraid you're right. I'm going to wait a bit more, maybe someone has a great idea but right now I'm trying to get my build tool take care of it. If this fails, I guess a script editing the javadoc file is the last option. I'll file the problem as well, maybe at some point an intern will update it :) – Vince Nov 12 '12 at 14:28

3 Answers3

12

values is a static method and is not subject to overriding. You cannot provide your own method to replace the generated one, and this is by specification.

There is no standard mechanism to replace the Javadoc of a method whose source code you don't control, but you could probably mess around with either the build tool, or, if all else fails, the final Javadoc HTML.

Marko Topolnik
  • 195,646
  • 29
  • 319
  • 436
  • The question title was misleading (it's now fixed). The question is *actually* about changing the *Javadoc* of the method, not its code. – Joachim Sauer Nov 12 '12 at 14:02
  • @JoachimSauer It's the same thing because you won't be able to provide Javadoc without declaring the method. – Marko Topolnik Nov 12 '12 at 14:04
1

I don't think this is possible, but you could file a JDK issue and maybe provide an OpenJDK fix, if you like.

Puce
  • 37,247
  • 13
  • 80
  • 152
  • yes maybe filing an issue to tell them to have more standard code in their example, it could be better. – Vince Nov 12 '12 at 14:21
  • 1
    Yes, but I could imagine it will get a low priority, that's why I also suggested to provide a fix, if you want to have it ASAP. – Puce Nov 12 '12 at 14:25
  • This cannot be an OpenJDK fix because it is [per specification](http://docs.oracle.com/javase/specs/jls/se7/html/jls-8.html#jls-8.9.2), making it 99.9% definite. – Marko Topolnik Nov 12 '12 at 15:37
  • @MarkoTopolnik True, this seems to be a spec change. :-/ Though it would be a backwards compatible one. So the issue has to be filed against the JLS not the JDK then (or both) and the JLS would have to be updated (patched) as well. – Puce Nov 12 '12 at 16:32
1

From the Oracle Java Tutorials:

The enum declaration defines a class (called an enum type). The enum class body can include methods and other fields. The compiler automatically adds some special methods when it creates an enum. For example, they have a static values method that returns an array containing all of the values of the enum in the order they are declared.

So, the method values cannot be overridden, since it's a special method created by the compiler. The Eclipse IDE generates this error when you try to do so:

The enum (your enum) already defines the method values() implicitly

Gilberto Torrezan
  • 5,113
  • 4
  • 31
  • 50