Issue #2514582 by Mile23, joachim, sahil.goyal, jhodgdon, Fabianx, dawehner: Document lazy services and fix script doxygen

(cherry picked from commit 85b4d86cb4)

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
  * @{

core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php

@@ -9,6 +9,9 @@ use Symfony\Component\Console\Input\InputInterface;
 
 /**
  * Provides a console command to generate proxy classes.
+ *
+ * @see lazy_services
+ * @see core/scripts/generate-proxy.sh
  */
 class GenerateProxyClassApplication extends Application {
 

core/lib/Drupal/Core/Command/GenerateProxyClassCommand.php

@@ -10,6 +10,9 @@ use Symfony\Component\Console\Output\OutputInterface;
 
 /**
  * Provides a console command to generate proxy classes.
+ *
+ * @see lazy_services
+ * @see core/scripts/generate-proxy.sh
  */
 class GenerateProxyClassCommand extends Command {
 

core/lib/Drupal/Core/DependencyInjection/Compiler/ProxyServicesPass.php

@@ -9,6 +9,8 @@ use Symfony\Component\DependencyInjection\Reference;
 
 /**
  * Replaces all services with a lazy flag.
+ *
+ * @see lazy_services
  */
 class ProxyServicesPass implements CompilerPassInterface {
 

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;