I think really instead of documentation the Java generator shouldn't be clobbering constants defined in separate thrift files.
To the best of my understanding, most users are defining all constants in one file for each namespace so this doesn't become an issue. Documented or not, it still doesn't seem like a reasonable constraint for how you're allowed to define constants.
I have this patched in my local copy to just generate a separate .java file containing constants for each program (.thrift file) that contains them. This might not be an ideal solution for everyone but it's how I worked around it.
Any other suggestions?