[TASK] Better document extbase defaultQuerySettings behavior

Extbase tends to become a victim of its own magic. In this
case, whenever a repository method like initializeObject()
uses setDefaultQuerySettings(), it fully overrides potentially
useful settings created by the factory.
Developers struggle here since all of a sudden things like
storagePid restrictions from configuration are no longer
applied.
We can't change this behavior easily - it would require some
awful dirty handling in QuerySettingsInterface, leading to
even more opaque complexity in this area.
The change adds comments to the property and the setter
hinting about the behavior.

Resolves: #89295
Releases: master, 10.4
Change-Id: I3b99dfa6d5a7881caaa952672386c00ebfa0166c
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/69324


Tested-by: Oliver Bartsch <bo@cedev.de>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Daniel Goerz <daniel.goerz@posteo.de>
Reviewed-by: Oliver Bartsch <bo@cedev.de>
Reviewed-by: Christian Wolff <chris@wolffc.de>
Reviewed-by: Daniel Goerz <daniel.goerz@posteo.de>

typo3/sysext/extbase/Classes/Persistence/Repository.php

@@ -48,6 +48,9 @@ class Repository implements RepositoryInterface, SingletonInterface
     protected $defaultOrderings = [];
 
     /**
+     * Override query settings created by extbase natively.
+     * Be careful if using this, see the comment on setDefaultQuerySettings() for more insights.
+     *
      * @var \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface
      */
     protected $defaultQuerySettings;
@@ -183,9 +186,15 @@ class Repository implements RepositoryInterface, SingletonInterface
     }
 
     /**
-     * Sets the default query settings to be used in this repository
+     * Sets the default query settings to be used in this repository.
+     *
+     * A typical use case is an initializeObject() method that creates a QuerySettingsInterface
+     * object, configures it and sets it to be used for all queries created by the repository.
      *
-     * @param \TYPO3\CMS\Extbase\Persistence\Generic\QuerySettingsInterface $defaultQuerySettings The query settings to be used by default
+     * Warning: Using this setter *fully overrides* native query settings created by
+     * QueryFactory->create(). This especially means that storagePid settings from
+     * configuration are not applied anymore, if not explicitly set. Make sure to apply these
+     * to your own QuerySettingsInterface object if needed, when using this method.
      */
     public function setDefaultQuerySettings(QuerySettingsInterface $defaultQuerySettings)
     {