Let's explain in DestructableInterface why it is useful

And we should document where this interface is used, namely with the "needs_destruction" tag for services. I just had to reverse engineer that since searching for the interface name yielded no results and I wanted to know where the actual destruction happens.

klausi opened a new pull request for this issue.

Great!

One small nitpick: in the core.api.php section of the patch:

+ *   instantiated. Services should implement the
+ *   \Drupal\Core\DestructableInterface in this case.

I would take out "the". We usually just say "Foo implements BarInterface" not "Foo implements *the* BarInterface".

Other than that, looks good to me and if "the" is removed I'd be in favor of RTBC.

Regarding @service_tag, that has not been adopted yet. See
#2264047: [meta] Document service definition tags

klausi pushed some commits to the pull request.

For an interdiff please see the list of recent commits.

So... these look like good improvements to make, but none of them actually does what the issue title states, which is explain why DestructableInterface is useful. :)

 /**
  * The interface for services that need explicit destruction.
+ *

Can we add a thing under here like:

/**
  * The interface for services that need explicit destruction.
  * 
  * This is useful for services that are likely to terminate before the 
  * request formally ends.

...or whatever the actual reason you'd implement this as a module developer is?

Added information requested in #8. Thanks for input!

I kept it terse and close to recommended text, but included a bit about rebuild/recreation due to use in caching or similar - not just termination.

Hm. There seems to be some disagreement... In core.api.php we have:

  * - 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.

Then in the interface, it says:

+ *
+ * This is useful for services that are likely to need termination or rebuild
+ * before the request formally ends.
+ *
+ * Services using this interface need to be registered with the
+ * "needs_destruction" tag.

So in the core.api.php file, it indicates that destruct() is called at the end of the request, but in the interface, it kind of implies that it could get rebuilt or terminated before the request ends. This is confusing to me. How would it get rebuilt??!? It seems like all that happens is that the destruct() method gets called, which I think is not a rebuild, and it's at the very end of the request...

So it seems like really what this means is that if your service class can just get destroyed normally when the PHP class goes away (or using the usual PHP class desctructor method), you don't need this interface, but if you have some kind of cleanup to do, you need this, right? What would be an example?

At first look I assumed that it was both : extending DestructableInterface (and setting the tag) gave you a ready-baked way to destroy (and control what destruction meant with ::destruct()) at the end of the request, as well as offering a method to reinitialize it on demand if desired. I will admit I can now find no use of the latter in the API:

https://api.drupal.org/api/drupal/core!lib!Drupal!Core!DestructableInterface.php/interface/DestructableInterface/8

And in fact 'destruct' doesn't even remotely imply reincarnation-like behavior. I think your confusion is valid, and agree that the documentation should only show the first case.

Enclosed are discussed changes. Thanks for review!

Regards.

Sure thing - thanks for review. Requested changes are attached.

Looks good to me, thanks!

Thanks, this makes the purpose of the interface more clear. "The interface for services that need explicit destruction" was kind of intriguing and dramatic by itself. ;)

This issue only changes documentation, so per https://www.drupal.org/core/beta-changes, this can be completed any time during the Drupal 8 beta phase. Committed and pushed to 8.0.x (with credit for reviewers).