diff --git a/core/core.api.php b/core/core.api.php
index d99e96715f37a33df05a257a28461851cd2bcc07..134bb9855c1e7dc7419ee0fd2db054e198db47d2 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 2a190f1d188966bb1356aa278b21bed767568e65..2a36dde2845c79db48a7191036d47da6b8093209 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 0dc481c63597f0a32a05ee75d3eb40282cee0a54..c34da7f38d0de0936f17cca7e25106d3a6411836 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;