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.

I've updated the documentation for the defaultStorageSettings() and defaultFieldSettings() methods to specify that setting names must be unique between them, as requested.

Thanks!

The wording is good, but @note is not a docs tag supported in the list at https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... →

Thanks for the feedback! I’ve removed the unsupported @note tag, kept the explanation in the standard comment format and fixed the coding standards.

Thanks!

But all the @return docs must be a single paragraph -- see https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... → .

I’ve adjusted the docblock formatting to ensure compliance with Drupal coding standards.

Thank you for your help!

Going to go on a limb and believe this one is complete.

@isalmanhaider, Instead of uploading screenshots of your IDE to bring attention to code, use a link to the file on GitLab, https://git.drupalcode.org/project/drupal.

Setting to needs work for #12. In that comment @joachim asked for the addition in the main part of the doc block. Right now, it is in the description of the return array.

Looks great. Thanks!

Committed/pushed to 11.x and cherry-picked to 11.2.x, thanks!

catch → closed merge request !9638

Automatically closed - issue fixed for 2 weeks with no activity.