API page: https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Entity%21...
It's not entirely clear what the 'current revision' means. Is it the published one, or is it the most recent?
I think it would help to make this explicit, and to also state that the use of currentRevision()/allRevisions() methods basically switches the query between the base table and the revisions table of the entity.
