Adding API docs and minor fixes.
Flow change - use after_build handler to mark the entity, and make the check in the entity_update.