defaultStorageSettings() and defaultFieldSettings() should document that they must not have setting names in common

Explanation:

In Drupal 11, the FieldItemInterface includes two methods: defaultFieldSettings() and defaultStorageSettings(). These methods define default settings for field items at different levels:

- defaultFieldSettings(): Specifies default settings at the field level.
- defaultStorageSettings(): Specifies default settings at the storage level.

Issue:

The methods are expected to return settings with unique names. This is crucial because other parts of the core, like BaseFieldDefinition, merge these arrays. Overlapping names can lead to conflicts or unexpected behavior.

Solution:

Document in both methods that setting names must be distinct to avoid such issues.

We are going to take this issue as part of the Symetris → contribution workshop.

Fixes are made on on 11.x (our main development branch) first, and are then back ported as needed according to our policies.

I guess this issue never made it into the workshop. We can work on it in Barcelona.

This issue require to write some docs into the comments of the code.

Updated docblock in defaultStorageSettings() method to specify the need for unique setting names.
Updated docblock in defaultFieldSettings() method with similar instructions.

I have reviewed the documentation for the both methods and those are different from the ones returned by the other method and now it totally makes distinct and can avoid conflicts.

- * A list of default settings, keyed by the setting name.
+ * A list of default settings, keyed by the setting name. Each setting name
+ * must be unique to avoid conflicts when these arrays are merged by other
+ * components in the core, such as BaseFieldDefinition.

This doesn't describe the problem.

They are obviously unique, since they are array keys!

We need to say unique with the OTHER method.

There's no point mentioning BaseFieldDefinition explicitly.

Something like this in the main body of the method docs:

> Setting names defined by this method must not duplicate the setting names returned by this plugin's implementation of OTHER METHOD, as both lists of settings are merged.