ISPN-3681 enhance the documentation of the new persistence API

https://issues.jboss.org/browse/ISPN-3681