TypedData's "Any" @DataType plugin has unclear documentation

@skyredwang

Data model changes

This type no longer can store array, primitive or known object implementing complex data interface.

The goal may be not ideal:

Reason:

1. All datas that is an object should use 'any' type data no matter whether it implementing complex data interface.
   Because no other type data can be or should be used to store object.
2. 'any' type data should have the ability to store any primitive data, Just like plugin system, we may pass different primite type of data to it on different plugin instance

Conclusion

1. The 'any' type data should be the last choice when module don't have any other suitable choice, It should have the ability to store any data, So we shouldn't add any condition to it on setValue()
2. What we should do is: When module come to the situation(.....) to use 'any', we should make these situation can be serialized

   possible situation:

   1. Object:when pass an object to any, don't just return the object, return the result of normalize(object)

Make class Any overwrite setValue to add conditions

1. don't allow array data
2. don't allow data that implements ComplexDataInterface
3. don't allow data that implements PrimitiveInterface

List:

core/core.api.php#n994

List data types, with interface \Drupal\Core\TypedData\ListInterface,
represent data that is an ordered list of typed data, all of the same type.

core/lib/Drupal/Core/TypedData/Annotation/DataType.php#n21

Furthermore, lists of data items are represented by objects implementing the
\Drupal\Core\TypedData\ListInterface. A list contains items of the same data
type，the plugins in the list must have the same base plugin ID;

Map:

core/core.api.php#n984

The base type for most complex data is the
\Drupal\Core\TypedData\Plugin\DataType\Map class, which represents an associative array

We can see that both *map* and *list* represents a diferent subset of Array

So all map and list's setValue() check whether the value is an array is correct(the father of data that map and list should reprents)

core/lib/Drupal/Core/TypedData/Plugin/DataType/ItemList.php#n58

      if (!is_array($values)) {
        throw new \InvalidArgumentException('Cannot set a list with a non-array value.');
      }

core/lib/Drupal/Core/TypedData/Plugin/DataType/Map.php#n75

     if (isset($values) && !is_array($values)) {
      throw new \InvalidArgumentException("Invalid values given. Values must be represented as an associative array.");
    }

Come to Any

Any:

core/lib/Drupal/Core/TypedData/Plugin/DataType/Any.php#n10

The "any" data type does not implement a list or complex data interface, nor
 is it mappable to any primitive type. Thus, it may contain any PHP data for
 which no further metadata is available.  

Let's fouced on: any PHP data for "which no further metadata is available"

The core/core.api.php#n941 describe the metadata here:

The metadata of a data object is defined by an object based on a class called the definition class

Conclusion

The list or complex data interface corresponding to the typed data, not the value stored by typed data
So we shouldn't forbid any typed data store data which implement ComplexDataInterface,ListInterface or PrimiteInterface

So If we add condition on any.php's setValue() according to doc(Not sure whether we should add condition)
we should forbid the data which implements DataDefinitionInterface

  class Any extends TypedData {

  protected $value;

  public function setValue($value, $notify = TRUE) {
    if (is_array($value) && $value instanceof DataDefinitionInterface) {
      throw new \InvalidArgumentException("Invalid value given, Value must not be implement DataDefinitionInterface.");
    }
    parent::setValue($value, $notify);
  }
}

If the 'any' doc is the formal specification,The above is the right formal implementation

Above formal implementation make a restrictions on 'any'
we can't store a typed data to a typed data of 'any'

So If we add condition on any.php's setValue() according to doc(Not sure whether we should add condition)
we should forbid the data which implements DataDefinitionInterface

Isn't the usecase of any when you simply don't know upfront? Just imagine storing arbitrary JSON, which could be all of the different variants you listed above ...

I think agree with @dawehner here

The doc in Any

* The "any" data type does not implement a list or complex data interface, nor
 * is it mappable to any primitive type. Thus, it may contain any PHP data for
 * which no further metadata is available.

might not be very clear.

I wonder the intention of the last sentence is actually

Thus, it may contain any PHP data for which no further metadata is available beforehand.

Meaning you can store values have metaData but you if you have metadata beforehand about what type of data you will be storing you should not use Any.

@tedbow
I agree with you and @dawehner
I add the word 'beforehand' @tedbow write to the doc on 2915052-8.patch, Please forgive my directing use of what you write, I want to accelerate the fixing of the issue, then hope @fago can review the patch, he wrote the origin comment on https://www.drupal.org/node/1913328

API-First issue #2915705: TypedData 'Any' can't be normalized to array if it stores an object triggered this.

I agree with #10. But I think we can still include the relevant bit of the first sentence, in a much clearer way (thanks to #10). Since I didn't do literally what #10 suggested, I can't RTBC this.

This makes it a lot cleaner, thanks Wim!

Hm, so I'm not sure just swapping the order of the sentences makes it any clearer...

How about adding an example?

Also the summary claims this is a data model change but the issue title says it's a docs fix?

Thanks!

This issue is being reviewed by the kind folks in Slack, #needs-review-queue-initiative. We are working to keep the size of Needs Review queue [2700+ issues] to around 400 (1 month or less), following Review a patch or merge request as a guide.

Tagging for IS per #14 asking for an example.