Issue #3151800 by pameeela, ayushmishra206, paulocs, adityasingh, quietone,...

Issue #3151800 by pameeela, ayushmishra206, paulocs, adityasingh, quietone, Bobík, longwave, Chris Burge: Describe what setInternal does

(cherry picked from commit e3cedd07)

core/lib/Drupal/Core/TypedData/DataDefinition.php

@@ -377,6 +377,8 @@ public function isInternal() {
    *   Whether the data value should be internal.
    *
    * @return $this
+   *
+   * @see \Drupal\Core\TypedData\DataDefinitionInterface::isInternal
    */
   public function setInternal($internal) {
     $this->definition['internal'] = $internal;

core/lib/Drupal/Core/TypedData/DataDefinitionInterface.php

@@ -224,6 +224,11 @@ public function addConstraint($constraint_name, $options = NULL);
    * This can be used in a scenario when it is not desirable to expose this data
    * value to an external system.
    *
+   * The implications of this method are left to the discretion of the caller.
+   * For example, a module providing an HTTP API may not expose entities of
+   * this type, or a custom entity reference field settings form may
+   * deprioritize entities of this type in a select list.
+   *
    * @return bool
    *   Whether the data value is internal.
    */