Improve documentation of "base hook" in hook_theme().

Attached is a patch against 8.x to amend the documentation (new text in bold):

base hook: A string declaring the base theme hook if this theme implementation is actually implementing a suggestion for another theme hook. When theme() is called on this hook, it will become the first theme hook suggestion for the base hook. Any of the base hook's include files will be loaded. If the base hook has any preprocess functions, they will take the place of this hook's preprocess functions. If any hook_theme_suggestions_HOOK() (where HOOK is the base hook) implementations change the order of hook suggestions, this hook may not be invoked. If this hook remains as the best suggestion after hook_theme_suggestions_HOOK(), then its function or template will be used to generate the output of theme().

Totally agreed: on principle I hate pronouns. Unfortunately though, without diving into using example code, it is not obvious to me how to refer to "the hook that is the key in the $themes array being returned by the respective hook_theme() that specifies 'base hook'" without referring to itself as "this hook." I piggy-backed on the original documentation which self-references as "this theme implementation," although honestly that's also a bit confusing.

So, "this" is hard to avoid, but maybe it can be better qualified.

base hook: A string declaring the base theme hook if this theme implementation is actually implementing a suggestion for another theme hook. If base hook is specified, when theme("example_theme_suggestion", $variables) is called, instead of being invoked directly this theme hook ("example_theme_suggestion") will become the first theme hook suggestion for the base hook. Any of the base hook's include files will be loaded. If the base hook has any preprocess functions, they will take the place of this theme suggestion's preprocess functions. If any hook_theme_suggestions_HOOK() (where HOOK is the base hook) implementations change the order of hook suggestions, this theme suggestion ("example_theme_suggestion") may not be invoked. If however, this suggestion remains the top suggestion after hook_theme_suggestions_HOOK(), then this suggestion's function or template will be used to generate the output of theme().

I tried to qualify "this" with "this theme suggestion" language, since the first sentence of the existing documentation already establishes that by using "base hook" you are specifying that the theme implementation is a suggestion. I couldn't resist sprinkling a little "example_theme_suggestion" around to try to clarify the meaning; I hope that's okay (this is my first stab at core documentation).

If we can find consensus on verbiage, I'll gladly roll another patch - I just don't want to attach several files if the perfect wording takes a while to discover.

How about this?

base hook: A string declaring the base theme hook if this theme implementation is actually implementing a suggestion for another theme hook. If base hook is specified, when theme() is called on this implementation, instead of being invoked directly the base hook will be called with this implementation as the first theme hook suggestion.

For example, if the outermost key returned by hook_theme() is 'image__example' and its 'base hook' value is 'image', then:

1. If the base hook ('image') has preprocess functions, they will take the place of 'image__example' preprocess functions, and any 'image__example' preprocess functions will not be executed.
2. If any hook_theme_suggestions_image() implementations change the order or set of hook suggestions, 'image__example' may be overridden. If however, the 'image__example' remains as the top suggestion after hook_theme_suggestions_image(), then the 'image__example' theming function or template will be used to generate the output of theme().

I'm not entirely sure that it's accurate to say "theme() is not called on an 'implementation'", at least not based on what I'm finding in the docs (should we create issues to clean those up, as well?) Here are some counter-examples I found.

theme() docs (both D7, D8) refer to theme() invoking some implementation:

Modules ... provide a default implementation via a function named theme_HOOK() (e.g., theme_taxonomy_term())

They also make explicit mention of the returns from hook_theme() being implementations:

Themes can override a default implementation by implementing a function named THEME_HOOK() (for example, the 'bartik' theme overrides the default implementation of the 'menu_tree' theme hook by implementing a bartik_menu_tree() function)

The hook_theme() docs themselves also say that the return from hook_theme are discrete implementations (invoked by theme()):

The implementations declared by this hook have two purposes: either they specify how a particular render array is to be rendered as HTML (this is usually the case if the theme function is assigned to the render array's #theme property), or they return the HTML that should be returned by an invocation of theme().

The remainder of the hook_theme() docs continue to use "implementation" throughout, and many parts of the @return are documented as "this implementation" or "this theme implementation" specifically. Some examples:

template: If specified, this theme implementation is a template...

base hook: A string declaring the base theme hook if this theme implementation...

pattern: A regular expression pattern to be used to allow this theme implementation...

function: If specified, this will be the function name to invoke for this implementation...

file: The file the implementation resides in...

From all of that, "implementation" seems to be the standardized terminology, and "theme hook" the outlier. Regardless of which is which, the rest of the docs need to be tidied up to reflect a consistent interpretation.

If we settle on "implementation," perhaps instead of rewriting the docs to change "this implementation" language (which is already abundantly used), we could get away with better defining the terminology in @return so it's less confusing. Looking at the top of @return, it refers to the returned outer keys as "hook names" (even though the @return is the first time in the docs that "hook" is used in this way), and then suddenly it changes terminology and says "Use 'variables' if your theme implementation..."; that's really a confusing change and should be introduced better and earlier.

Here's an attempt at ditching "hook" in favor of "implementation" (which is what the rest of the text refers to; a "theme hook" is an anomaly in @return: even the summary of hook_theme() is "Register a module (or theme's) theme implementations."):

array An associative array of theme hook information implementations. The keys on the outer array are the internal names of the hook implementations, and the values are information arrays containing information about the hook each implementation. Each information array must contain either a 'variables' element or a 'render element' element, but not both. Use 'render element' if you are the implementation is theming a single element or element tree composed of elements, such as a form array, a page array, or a single checkbox element. Use 'variables' if your the theme implementation is intended to be called directly through theme() and has multiple arguments for the data and style; in this case, the variables not supplied by the calling function will be given default values and passed to the template or theme function. The returned theme information array can contain the following key/value pairs (note: for the rest of this section, "the/this implementation" refers to the outer key of the return array and its associated information array):

The array elements in the return value of hook_theme() are information about theme hooks (including telling the theme system where to find the implementation).

It looks like you've fallen into the same trap - "where to find the implementation" is certainly not the same as "where to find the hook" if I'm returning a new implementation of "image," the original implementation for which exists in theme.inc.

I think it's so confusing because hook_theme() provides dual functionality. Either you're returning new theme hooks and their specifications (which according to the docs requires a default implementation, so implicitly you are also specifying your implementation with hook_theme()), or you are registering your own implementation of an existing hook.

The extant docs for theme() and hook_theme() lean toward the more generic case (returning implementations), but Default theme implementations says that hook_theme() defines hooks. Clearly the docs themselves can't make up their minds.

Anyway, arguing semantics is moot and beyond the intended scope of this issue. If we need to overhaul several doc pages to standardize nomenclature, that's fine, but it needs its own set of issues and definitely more people looking at it than just the two of us. I am merely trying to provide an incremental improvement to the existing docs, written in a consistent manner with the surrounding text. A larger issue requires... well, a larger issue ticket.

Well, we either proceed with edits to hook_theme() to bring the whole page inline with itself (simpler), or tear up everything across theme(), hook_theme(), Default theme implementations, etc. (harder). To accomplish the latter, a new issue should be created and this one postponed until that other issue is resolved - it doesn't make sense to co-opt an issue which is only tangentially related to the nomenclature problem.

For what it's worth, I agree more with the current hook_theme() and theme() documentation (and comments in code) interpretation: what you are defining in hook_theme() are implementations of a hook. That's how the rest of Drupal's hook system works: you define implementations of hook_init() (and you put "Implements hook_init()." as a comment right above the relevant function). Likewise, you implement theme hooks. That makes sense to me (and apparently to the original authors), so I'd argue for standardizing in that direction, not the reverse.

Expanding on that thought, it makes very little sense to say "file - here's where the hook's file lives." Hooks are specifications, not implementations - if anything, they "exist" in something.api.php. The actual implementation has a file where it lives. But, to argue against myself, hook_theme()'s returns also delineate "variables" which arguably should be part of the specification, not the implementation. So we're back to the dual-use of hook_theme() and its corresponding confusion; in the end, neither interpretation is decidedly "wrong." That's a unilateral decision with little to recommend it.

I like it! But the "base hook" piece needs tweaking for accuracy. How about this?

Here's what I changed:

@@ -86,8 +86,10 @@
 + *   - base hook: Used for theme() suggestions only: the base theme hook name.
-+ *     This suggestion will become the first suggestion to be searched for in
-+ *     a call to theme(), unless an implementation of
-+ *     hook_theme_suggestions_HOOK() changes the order. If this suggestion is
-+ *     chosen, its include files will be loaded and its preprocess functions
-+ *     will be called in place of the base hook's preprocess functions, and then
-+ *     its function or template will be used to generate the output for theme().
++ *     Any of the base hook's files will be included and the base hook's
++ *     preprocess functions will be called in place of any preprocess functions
++ *     for the suggestion. If an implementation of hook_theme_suggestions_HOOK()
++ *     (where HOOK is the base hook) changes the suggestion order, the
++ *     suggestion being defined here may not be used to generate the output for
++ *     theme(). If the order of suggestions is not changed, then this
++ *     suggestion's function or template will be used to generate the output for
++ *     theme(), but any of its preprocessors still will not be called.

The thing is (and this was the not-so-obvious thing that lead me to want to improve the docs in the first place), the base hook does not become a suggestion - it basically becomes the hook that is invoked up until the very last stage (where the template file or function is used). The base hook's files are always included, its preprocessors are always run (instead of any other suggestion's preprocessors), and that happens before any suggestions are searched. The only place the suggestions come into play is in the very last step, when the suggestion's function or template file is used to generate the output.

I've taken another stab at it; how's this? Sorry for the lack of interdiff previously - I had never stumbled on https://drupal.org/documentation/git/interdiff before!