Hi Roland Illig, thanks for reporting this, looks dodgy indeed.

I'm not convinced this is strictly a documentation issue. Some people will only be reading the JPA API javadoc so it would be nice to have the implementation to conform to the API it promises, however in this specific case this might imply having to remove support for enhancement of final entities. (Which has always been discouraged).

I'll bring it to the attention of the mailing list.