Issue #2447365 by JacobSanford, klausi, dawehner, jhodgdon, webchick: Let's...

Issue #2447365 by JacobSanford, klausi, dawehner, jhodgdon, webchick: Let's explain in DestructableInterface why it is useful

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

@@ -13,6 +13,8 @@
 /**
  * Adds services tagged "needs_destruction" to the "kernel_destruct_subscriber"
  * service.
+ *
+ * @see \Drupal\Core\DestructableInterface
  */
 class RegisterServicesForDestructionPass implements CompilerPassInterface {
 

core/lib/Drupal/Core/DestructableInterface.php

@@ -9,6 +9,13 @@
 
 /**
  * The interface for services that need explicit destruction.
+ *
+ * This is useful for services that need to perform additional tasks to
+ * finalize operations or clean up after the response is sent and before the
+ * service is terminated.
+ *
+ * Services using this interface need to be registered with the
+ * "needs_destruction" tag.
  */
 interface DestructableInterface {
 

core/lib/Drupal/Core/EventSubscriber/KernelDestructionSubscriber.php

@@ -14,6 +14,8 @@
 
 /**
  * Destructs services that are initiated and tagged with "needs_destruction".
+ *
+ * @see \Drupal\Core\DestructableInterface
  */
 class KernelDestructionSubscriber implements EventSubscriberInterface, ContainerAwareInterface {
 

core/modules/system/core.api.php

@@ -2152,7 +2152,8 @@ function hook_config_schema_info_alter(&$definitions) {
  *   for more information.
  * - needs_destruction: Indicates that a destruct() method needs to be called
  *   at the end of a request to finalize operations, if this service was
- *   instantiated.
+ *   instantiated. Services should implement \Drupal\Core\DestructableInterface
+ *   in this case.
  *
  * Creating a tag for a service does not do anything on its own, but tags
  * can be discovered or queried in a compiler pass when the container is built,