document entity-fields behavior

Also cleaned up some other minor issues around what my change.