hook_theme_suggestions() hook_theme_suggestions_HOOK() documentation is incorrect about how the hook is invoked

Thanks @ClientGuy :)

+++ b/core/modules/system/theme.api.php
@@ -492,7 +492,7 @@ function hook_preprocess_HOOK(&$variables) {
  * This hook allows the module implementing hook_theme() for a theme hook to
  * provide alternative theme function or template name suggestions. This hook is
- * only invoked for the first module implementing hook_theme() for a theme hook.
+ * invoked for all modules implementing hook_theme() for a theme hook.

The hook is invoked for all modules, period. So this whole paragraph should be updated, something like this might do it:

"This hook allows modules to provide alternative theme function or template name suggestions."

Much closer, thanks!

1. +++ b/core/modules/system/theme.api.php
   @@ -490,9 +490,8 @@ function hook_preprocess_HOOK(&$variables) {
   + * This hook allows modules to provide alternative theme function or template
   + * name suggestions. This hook is invoked for all modules.
   

   Arguably "This hook is invoked for all modules" is the default and therefore redundant, but I'm fine either way on that. Might be worth looking around at other *.api.php's as an example.

2. +++ b/core/modules/system/theme.api.php
   @@ -490,9 +490,8 @@ function hook_preprocess_HOOK(&$variables) {
     * HOOK is the least-specific version of the hook being called. For example, if
     * '#theme' => 'node__article' is called, then node_theme_suggestions_node()
   

   This part actually should be updated too I think, because it seems to reflect the previous paragraph where only the module implementing hook_theme() would get the hook invocation.

   Here's the full couple sentences:

   HOOK is the least-specific version of the hook being called. For example, if '#theme' => 'node__article' is called, then node_theme_suggestions_node() will be invoked, not node_theme_suggestions_node__article().

@harshil.maradiya - Patch is corrupt according to git, missing newline at EOF I think.

All my comments from #10 still apply. I don't think we should change the docs for hook_theme_suggestions_HOOK_alter() in this issue. Can we go back to the patch from #9 please and provide interdiffs when making changes to patches? Thanks all! :)