From 85b4d86cb4a23e3596d892a81555f3c3e9be23d0 Mon Sep 17 00:00:00 2001
From: catch <catch@35733.no-reply.drupal.org>
Date: Mon, 28 Nov 2022 13:16:04 +0000
Subject: [PATCH] Issue #2514582 by Mile23, joachim, sahil.goyal, jhodgdon,
 Fabianx, dawehner: Document lazy services and fix script doxygen

---
 core/core.api.php                             | 30 +++++++++++++++++++
 .../Command/GenerateProxyClassApplication.php |  3 ++
 .../Command/GenerateProxyClassCommand.php     |  3 ++
 .../Compiler/ProxyServicesPass.php            |  2 ++
 core/scripts/generate-proxy-class.php         |  9 +++++-
 5 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/core/core.api.php b/core/core.api.php
index d99e96715f37..134bb9855c1e 100644
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -886,6 +886,10 @@
  *   Note that $container here is an instance of
  *   \Drupal\Core\DependencyInjection\ContainerBuilder.
  *
+ * @section lazy_services Lazy services
+ * Some services can be declared as lazy to improve performance. See @link
+ * lazy_services Lazy Services @endlink for details.
+ *
  * @see https://www.drupal.org/node/2133171
  * @see core.services.yml
  * @see \Drupal
@@ -2489,6 +2493,32 @@ function hook_validation_constraint_alter(array &$definitions) {
  * @}
  */
 
+/**
+ * @defgroup lazy_services Lazy Services
+ * @{
+ * Lazy services overview
+ *
+ * A service can be declared as lazy in order to improve performance. Classes
+ * that inject a lazy service receive a proxy class instead, and when a method
+ * on the lazy service is called, the proxy class gets the service from the
+ * container and forwards the method call. This means that the lazy service is
+ * only instantiated when it is needed.
+ *
+ * This is useful because some classes may inject a service which is expensive
+ * to instantiate (because it has multiple dependencies of its own), but is only
+ * used in exceptional cases. This would make the class dependent on the
+ * expensive service and all of the expensive service's dependencies.
+ *
+ * Making the expensive service lazy means that the class is only dependent on
+ * the proxy service, and not on all the dependencies of the lazy service.
+ *
+ * To define a service as lazy, add @code lazy: true @endcode to the service
+ * definition, and use the @code core/scripts/generate-proxy.sh @endcode script
+ * to generate the proxy class.
+ *
+ * @see core/scripts/generate-proxy.sh
+ */
+
 /**
  * @defgroup events Events
  * @{
diff --git a/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php b/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php
index 2a190f1d1889..2a36dde2845c 100644
--- a/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php
+++ b/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php
@@ -9,6 +9,9 @@
 
 /**
  * Provides a console command to generate proxy classes.
+ *
+ * @see lazy_services
+ * @see core/scripts/generate-proxy.sh
  */
 class GenerateProxyClassApplication extends Application {
 
diff --git a/core/lib/Drupal/Core/Command/GenerateProxyClassCommand.php b/core/lib/Drupal/Core/Command/GenerateProxyClassCommand.php
index 0dc481c63597..c34da7f38d0d 100644
--- a/core/lib/Drupal/Core/Command/GenerateProxyClassCommand.php
+++ b/core/lib/Drupal/Core/Command/GenerateProxyClassCommand.php
@@ -10,6 +10,9 @@
 
 /**
  * Provides a console command to generate proxy classes.
+ *
+ * @see lazy_services
+ * @see core/scripts/generate-proxy.sh
  */
 class GenerateProxyClassCommand extends Command {
 
diff --git a/core/lib/Drupal/Core/DependencyInjection/Compiler/ProxyServicesPass.php b/core/lib/Drupal/Core/DependencyInjection/Compiler/ProxyServicesPass.php
index b37e900f560c..1b1f03577c98 100644
--- a/core/lib/Drupal/Core/DependencyInjection/Compiler/ProxyServicesPass.php
+++ b/core/lib/Drupal/Core/DependencyInjection/Compiler/ProxyServicesPass.php
@@ -9,6 +9,8 @@
 
 /**
  * Replaces all services with a lazy flag.
+ *
+ * @see lazy_services
  */
 class ProxyServicesPass implements CompilerPassInterface {
 
diff --git a/core/scripts/generate-proxy-class.php b/core/scripts/generate-proxy-class.php
index 2664739be423..a06293d5feff 100644
--- a/core/scripts/generate-proxy-class.php
+++ b/core/scripts/generate-proxy-class.php
@@ -3,7 +3,14 @@
 
 /**
  * @file
- * A command line application to generate proxy classes.
+ * A script to generate proxy classes for lazy services.
+ *
+ * For help, type this command from the root directory of an installed Drupal
+ * site: php core/scripts/generate-proxy-class.php -h generate-proxy-class
+ *
+ * @ingroup container
+ *
+ * @see lazy_services
  */
 
 use Drupal\Core\Command\GenerateProxyClassApplication;
-- 
GitLab