Issue #3345789 by andy-blum: Improve documentation of hook_theme_suggestions_HOOK()

 * must otherwise make sure that the hook implementation is available at

 * any given time.

 *

 * @todo Add @code sample.

 * Suggestions must begin with the value of HOOK, followed by two underscores to be discoverable.

 *

 * In the following example, we provide suggestions to

 * node templates based bundle, id, and view mode.

 *

 * @code

 * function node_theme_suggestions_node(array $variables) {

 *   $suggestions = [];

 *   $node = $variables['elements']['#node'];

 *   $sanitized_view_mode = strtr($variables['elements']['#view_mode'], '.', '_');

 *   $suggestions[] = 'node__' . $sanitized_view_mode;

 *   $suggestions[] = 'node__' . $node->bundle();

 *   $suggestions[] = 'node__' . $node->bundle() . '__' . $sanitized_view_mode;

 *   $suggestions[] = 'node__' . $node->id();

 *   $suggestions[] = 'node__' . $node->id() . '__' . $sanitized_view_mode;

 *

 *   return $suggestions;

 * }

 *

 * @endcode

 *

 * @param array $variables

 *   An array of variables passed to the theme hook. Note that this hook is