Permission API documentation improvement

A couple of unclarities were found in PicketLink documentation:

• Permission API documentation is not clear. The documentation is missing the fact that users need to provide permission handler, otherwise they would get following error: "org.picketlink.idm.IdentityManagementException: No permission handler registered for resource."
• Another issue in this chapter comes when BasicPermissionTypeEntity is not implemented and/or this class is not mapped in builder, after that NPE occurs. This needs to be documented.