I`ve created pull request https://github.com/hibernate/hibernate-orm/pull/1360, with the fix. But I`m still researching how to fix documentation.