Document the type of tables an entity type can define

Apparently, entity types can use four different tables to store their data (not counting field tables).

I had to Google this and find https://drupalwatchdog.com/blog/2015/3/entity-storage-drupal-8-way to understand what the tables are meant to do. Looking at \Drupal\Core\Entity\EntityType doesn't tell you much:

  /**
   * The name of the entity type's base table.
   *
   * @var string|null
   */
  protected $base_table = NULL;

  /**
   * The name of the entity type's revision data table.
   *
   * @var string|null
   */
  protected $revision_data_table = NULL;

  /**
   * The name of the entity type's revision table.
   *
   * @var string|null
   */
  protected $revision_table = NULL;

  /**
   * The name of the entity type's data table.
   *
   * @var string|null
   */
  protected $data_table = NULL;

Can we document this better and if so: Where would be the best place to do so?