diff --git a/core/core.api.php b/core/core.api.php
index 9ff2d55004cead5e1174215326d523297d8271de..312af5e12c6704ac84ccaccbfe2f44ef1f5b484b 100644
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -889,6 +889,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
@@ -2493,6 +2497,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 17d1e29360b6bcebb300ef349472c9662606c8cb..f51513aedcb9e59fce693ea54c5536541d7127ae 100644
--- a/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php
+++ b/core/lib/Drupal/Core/Command/GenerateProxyClassApplication.php
@@ -8,6 +8,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 ac99bc6c3a4f61d3e125c5ecfbb82bb6b2277932..be3c25d6ddf18ccba60bd1bc5dded9b3d5b9358d 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 b37e900f560cb1a264347d08b9bd50f97a03d61d..1b1f03577c98421fe4abc18dbf6390f61a750fb1 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 2664739be4232d161d5eff79505c801e26263bf8..a06293d5feff87eaa6fe20f6c01d822e814bb7b4 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;