TablesInterface::addField() doesn't document that $field can contain relationships

nishtha.pradhan → made their first commit to this issue’s fork.

Thank you @nishtha.pradhan, for your MR and for addressing the documentation for TablesInterface::addField() in Drupal core.

I've reviewed the changes provided in Drupal version 11.x. To enhance clarity, I suggest explicitly stating in the documentation that dot notation (.) can be used to specify fields involving relationships. This is consistent with practices observed in tests such as EntityQueryRelationshipTest.

For example:

/**
 * Adds a field to a database query.
 *
 * @param string $field
 *   The field to add to the query. Use dot notation to specify fields from
 *   related entities, e.g., "entity.field" or "entity:referenced_entity.field".
 *   Delta can be a numeric value or a "%delta" for any value.
 *   
 *   See {@link https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Query!QueryInterface.php/function/QueryInterface%3A%3Acondition/8.9.x QueryInterface::condition()} for more details.
 * @param string $type
 *   Join type, can either be INNER or LEFT.
 * @param string $langcode
 *   The language code to use for multilingual queries.
 *
 * @return string
 *   The return value is a string containing the alias of the table, a dot
 *   and the appropriate SQL column as passed in. This allows the direct use
 *   of this in a query for a condition or sort.
 *
 * @throws \Drupal\Core\Entity\Query\QueryException
 *   If $field specifies an invalid relationship.
 */
public function addField($field, $type = 'INNER', $langcode = NULL);

I would appreciate feedback from others on this proposed change. Does this approach align with the understanding of how fields should be specified in Drupal queries? Are there any additional considerations we should take into account?

Your thoughts and suggestions would be valuable.

Thank you!

Seems the updates were slightly copied and paste from the summary, but don't think we should be introducing new phrase that don't already exist.

For comprehensive documentation on the

is not found in core. Example

* See the @link themeable Default theme implementations topic @endlink for
* details.

That's just a suggestion, that may fit but should checkout other examples in the repo so we can stay more inline.

Nitpicky but good exercise, leaving the novice tag.

The @link syntax is for linking a topic. I'm not sure it'll work with a method name.

Just giving the full class name and method will make a link on api.d.org.