Roland Illig When you say to document it, do you mean to mention that, do you mean to add a warning message in the User Guide where we talk about entity proxies?

Related to updating the JavaDoc, we could only do it in SessionImpl, which practically is as useless as not doing it anyway since the vast majority of users will just read the JPA EntityManager, therefore omitting the Hibernate-specific implementation JavaDoc.