added documentation to entity state