Issue #3353693 by rckstr_rohan, joachim, smustgrave: the way QueryFactory and...

Issue #3353693 by rckstr_rohan, joachim, smustgrave: the way QueryFactory and Query work with namespaces and classes needs to be documented

core/lib/Drupal/Core/Entity/Query/Null/QueryFactory.php

@@ -20,6 +20,9 @@ class QueryFactory implements QueryFactoryInterface {
 
   /**
    * Constructs a QueryFactory object.
+   *
+   * Initializes the list of namespaces used to locate query
+   * classes for different entity types.
    */
   public function __construct() {
     $this->namespaces = QueryBase::getNamespaces($this);

core/lib/Drupal/Core/Entity/Query/QueryBase.php

@@ -468,6 +468,11 @@ protected function getAggregationAlias($field, $function) {
   /**
    * Gets a list of namespaces of the ancestors of a class.
    *
+   * Returns a list of namespaces that includes the namespace of the
+   * class, as well as the namespaces of its parent class and ancestors. This
+   * is useful for locating classes in a hierarchy of namespaces, such as when
+   * searching for the appropriate query class for an entity type.
+   *
    * @param $object
    *   An object within a namespace.
    *
@@ -486,6 +491,8 @@ public static function getNamespaces($object) {
   /**
    * Finds a class in a list of namespaces.
    *
+   * Searches in the order of the array, and returns the first one it finds.
+   *
    * @param array $namespaces
    *   A list of namespaces.
    * @param string $short_class_name

core/lib/Drupal/Core/Entity/Query/Sql/QueryFactory.php

@@ -32,6 +32,9 @@ class QueryFactory implements QueryFactoryInterface {
   /**
    * Constructs a QueryFactory object.
    *
+   * Initializes the list of namespaces used to locate query
+   * classes for different entity types.
+   *
    * @param \Drupal\Core\Database\Connection $connection
    *   The database connection used by the entity query.
    */

core/modules/workspaces/src/EntityQuery/QueryFactory.php

@@ -23,6 +23,9 @@ class QueryFactory extends BaseQueryFactory {
   /**
    * Constructs a QueryFactory object.
    *
+   * Initializes the list of namespaces used to locate query
+   * classes for different entity types.
+   *
    * @param \Drupal\Core\Database\Connection $connection
    *   The database connection used by the entity query.
    * @param \Drupal\workspaces\WorkspaceManagerInterface $workspace_manager