Problem/Motivation
There are standards for "Themeable functions" (theme_*() functions), but not preprocess functions. Part of the Twig conversion is removing theme functions and adding new preprocess functions, so there will be many more preprocess functions in core.
Quoting c4rl in #1825464-7: [meta] Documentation blocks for preprocess functions:
We've come to acknowledge that the word "preprocess" means different things to different people. For themers, it means "prepare and alter variables for a template file." For developers concerned with runtime, it means "typically unnecessary layer of execution that we may or may not eventually use before invoking a given template."
Proposed resolution
Template preprocess functions (template_preprocess_node(), for example) are documented using these standards:
- The first line should be "Prepares variables for…" and should describe what the template is used for rather than referring to the file name of the template.
- All components of the
$variablesarray need to be documented. - There should be a
@seereference pointing to the template file. - They should have
@ingroup themeablein their documentation.
Syntax example:
<?php
/**
* Prepares variables for the node template.
*
* Most themes utilize their own copy of node.html.twig. The default is located
* inside "modules/node/node.html.twig". Look in there for the full list of
* variables.
*
* @param $variables
* An associative array containing:
* - elements: An array of elements to display in view mode.
* - node: The node object.
* - view_mode: View mode; e.g., 'full', 'teaser'...
*
* @see node.html.twig
*
* @ingroup themeable
*/
function template_preprocess_node(&$variables) {
?>Remaining tasks
- Decide on standards.
- Update http://drupal.org/node/1354 as necessary.
User interface changes
n/a
API changes
n/a