hook_theme_suggestions_HOOK() is not clear enough about what should be returned

This sounds like a good idea! Do you want to provide a patch?

Hi ahmad.h.khalil,

Patch will be the good solution, people see the example in core files first,
so we change in core api, it would be more helpful for the user.

It is much more clearer using "hookname" instead of node.
Looks great. +1 to RTBC.

Hi @ahmad.h.khalil,

i Checked that how to change in api document, AS well as update in drupal core also, it would be helpful.

Thanks

Thanks

@ahmad.h.khalil Thank you for your interest in this issue. There are some things you should know:

• api.drupal.org is generated from the code.
• Because of that, changes are not effected until the code is committed.

I hope this helps!

@prajaankit Thank you for providing a patch on this documentation bug. Please be aware that all reviews are peer-based so it is not permitted to mark one's own patches as "Reviewed and tested by the community". Overall, you've done a nice job—please continue helping on issues!

One more thing: I have retitled this issue for clarity.

Changing the status to RTBC.
Manually applied the patch as mentioned in #9

I was wondering if hookname was the right thing or not, so did this:

$ git grep hookname
core/lib/Drupal/Core/Render/theme.api.php:    $suggestions[] = 'hookname__' . 'no_header';


$ git grep HOOKNAME
[ no results ]


$ git grep HOOK
core/includes/theme.inc: * hook_theme_suggestions_HOOK_alter() or adding to 'attributes' class key
core/includes/theme.inc: *   hook_theme_suggestions_HOOK_alter() or to $variables['attributes']['class']
core/lib/Drupal/Core/Entity/entity.api.php: * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
core/lib/Drupal/Core/Entity/entity.api.php: * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
core/lib/Drupal/Core/Render/theme.api.php: * called theme_HOOK, where HOOK is the name of the theme hook (for example,
core/lib/Drupal/Core/Render/theme.api.php: * defining a function called THEME_HOOK() in its THEME.theme file, where THEME
core/lib/Drupal/Core/Render/theme.api.php: * HOOK indicates the hook being called or a less specific hook. For example, if
core/lib/Drupal/Core/Render/theme.api.php: * - template_preprocess_HOOK(&$variables): Should be implemented by the module
core/lib/Drupal/Core/Render/theme.api.php: * - MODULE_preprocess_HOOK(&$variables): hook_preprocess_HOOK() is invoked on
core/lib/Drupal/Core/Render/theme.api.php: * - ENGINE_engine_preprocess_HOOK(&$variables): Allows the theme engine to set
core/lib/Drupal/Core/Render/theme.api.php: * - THEME_preprocess_HOOK(&$variables): Allows the theme to set necessary
core/lib/Drupal/Core/Render/theme.api.php: * preprocess functions (the ones ending in _HOOK) are called from the list
core/lib/Drupal/Core/Render/theme.api.php: * - A module can implement hook_theme_suggestions_HOOK(). This allows the
core/lib/Drupal/Core/Render/theme.api.php: * theme-hook-specific hook_theme_suggestions_HOOK_alter() and the generic
core/lib/Drupal/Core/Render/theme.api.php: * hooks implemented as functions. hook_preprocess_HOOK() can be used to
core/lib/Drupal/Core/Render/theme.api.php:function hook_preprocess_HOOK(&$variables) {
core/lib/Drupal/Core/Render/theme.api.php: * HOOK is the least-specific version of the hook being called. For example, if
core/lib/Drupal/Core/Render/theme.api.php: * @see hook_theme_suggestions_HOOK_alter()
core/lib/Drupal/Core/Render/theme.api.php:function hook_theme_suggestions_HOOK(array $variables) {
core/lib/Drupal/Core/Render/theme.api.php: * theme hook it's best to use hook_theme_suggestions_HOOK_alter().
core/lib/Drupal/Core/Render/theme.api.php: * hook_theme_suggestions_HOOK_alter(). So, for each module or theme, the more
core/lib/Drupal/Core/Render/theme.api.php: * @see hook_theme_suggestions_HOOK_alter()
core/lib/Drupal/Core/Render/theme.api.php: * hook_theme_suggestions_HOOK() or by earlier invocations of this hook.
core/lib/Drupal/Core/Render/theme.api.php: * HOOK is the least-specific version of the hook being called. For example, if
core/lib/Drupal/Core/Render/theme.api.php: * @see hook_theme_suggestions_HOOK()
core/lib/Drupal/Core/Render/theme.api.php:function hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
core/lib/Drupal/Core/Render/theme.api.php: *     functions. If an implementation of hook_theme_suggestions_HOOK() (where
core/lib/Drupal/Core/Render/theme.api.php: *     HOOK is the base hook) changes the suggestion order, a different
core/lib/Drupal/Core/Render/theme.api.php: *     hook_theme_suggestions_HOOK() this suggestion remains the first
core/lib/Drupal/Core/Render/theme.api.php: *     for a module this will be filled in as template_preprocess_HOOK. For
core/lib/Drupal/Core/Render/theme.api.php: *     twig_preprocess_HOOK as well as themename_preprocess and
core/lib/Drupal/Core/Render/theme.api.php: *     themename_preprocess_HOOK.
core/lib/Drupal/Core/Theme/ThemeManager.php:    // Invoke hook_theme_suggestions_HOOK().
core/lib/Drupal/Core/Theme/ThemeManager.php:    // hook_theme_suggestions_HOOK_alter().
core/lib/Drupal/Core/Theme/ThemeManager.php:    // via hook_theme_suggestions_HOOK_alter(), enabling a theme to have
core/modules/aggregator/aggregator.module: * Implements hook_preprocess_HOOK() for block templates.
core/modules/block/block.api.php: * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
core/modules/block/block.module: * Implements hook_theme_suggestions_HOOK().
core/modules/comment/comment.module: * Implements hook_preprocess_HOOK() for block templates.
core/modules/content_moderation/content_moderation.module: * Implements hook_preprocess_HOOK().
core/modules/content_moderation/src/ContentPreprocess.php:   * Wrapper for hook_preprocess_HOOK().
core/modules/content_translation/content_translation.admin.inc: * (proxied) Implements hook_preprocess_HOOK();
core/modules/content_translation/content_translation.module: * Implements hook_preprocess_HOOK() for language-content-settings-table.html.twig.
core/modules/filter/tests/src/Functional/FilterCaptionTwigDebugTest.php:    $this->assertTrue(strpos($output, '<!-- THEME HOOK: \'filter_caption\' -->') !== FALSE, 'filter_c

So apparently there is prior art for using hookname_.

In fact that is in:

function hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  if (empty($variables['header'])) {
    $suggestions[] = 'hookname__' . 'no_header';
  }
}

Which is the alter counterpart to this hook. So looks good to me.