Document why UserInterface + FileInterface + MenuLinkContentInterface + … extend \Drupal\Core\Entity\ContentEntityInterface

Well, ideally the revision stuff would live on \Drupal\Core\Entity\RevisionableContentEntityBase or a corresponding interface. At least the issue title as it is, is highly misleading :)

Yeah, we discussed this in IRC, the correct way to identify this is not this interface but to use isRevisionable() on the entity type, which basically checks if here is a revision entity key.

All content entities implement this interface, the reason is that they all *technically* support revisions just like they all technically support revisions and translations. Whether they actually have a its a question of storage/storage configuration, which is done in the annotation and that can be changed with alter hooks.

Changing to a documentation task as Wim promised to do (he said he'll close it actually, IIRC)

Thank you wim! I hope this clarifies the situation up.

Committed and pushed 481a2ad to 8.3.x and f783ca2 to 8.2.x. Thanks!

1. This looks helpful - nice docs. However, I ended up not committing because there are some simple improvements we can do.

2. +++ b/core/lib/Drupal/Core/Entity/RevisionableInterface.php
   @@ -4,6 +4,12 @@
   + * revisionability in conditional logic, use
   

   revisionability is not a word and this is the first instance in our code base. How about:
   To detect whether an entity type is revisionable in conditional logic, use EntityTypeInterface::isRevisionable().

3. +++ b/core/lib/Drupal/Core/Entity/RevisionableInterface.php
   @@ -4,6 +4,12 @@
   + * \Drupal\Core\Entity\EntityTypeInterface::isRevisionable().
   

   Let's add an @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable() and then we can use the short form in the documentation.

Wording is a bit repetitive (How would you detect something with non-conditional logic exactly?), but I guess it is hard to avoid that without inventing new words that alex doesn't like :)

Hmm I still don't know what exactly "in conditional logic" means. Isn't "conditional logic" redundant?

Maybe an example of what you should or should not do?

Maybe

You MUST NOT use this interface in instanceof checks...

?

Try this:

/**
 * Provides methods for an entity to support revisions.
 *
 * Classes implementing this interface do not necessarily support revisions.
 *
 * To detect whether an entity type supports revisions, call
 * EntityTypeInterface::isRevisionable().
 *
 * @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable()
 */
interface RevisionableInterface {

+++ b/core/lib/Drupal/Core/Entity/RevisionableInterface.php
@@ -4,6 +4,13 @@
+ *
+ * Classes implementing this interface do not necessarily support revisions.
+ *
+ * To detect whether an entity type supports revisions, call
+ * EntityTypeInterface::isRevisionable().
+ *
+ * @see \Drupal\Core\Entity\EntityTypeInterface::isRevisionable()
  */
 interface RevisionableInterface {

This needs a 'why', could be a paraphrase of #4.

Voila.

Hmm that doesn't cover the main reason for me, which is this:

Whether they actually have a its a question of storage/storage configuration, which is done in the annotation and that can be changed with alter hooks.

Research led to this: #2886622: Deprecate all EntityManager methods with E_USER_DEPRECATED

How about this?

That looks like it is a good improvement.

Committed and pushed b263f5c4d0 to 8.6.x and 600f720e85 to 8.5.x. Thanks!