Since I haven't seen it explicitly discussed anywhere else in this project, and I'm running up against several different variations in terminology, what can we agree is the best way to title and document template_preprocess functions?

I'll use theme('item_list') as an example.

a.

/**
 * Preprocess variables for an item list.
 */

b.

/**
 * Preprocess variables for theme('item_list').
 */

...?

Comments

steveoliver’s picture

c.

/**
 * Preprocess variables for item list templates.
 */
steveoliver’s picture

d.

/**
 * Preprocess variables for item list template.
 */

prefer C. so far.

jenlampton’s picture

I also like C :)

artofeclipse’s picture

C looks good for me :)

vlad.dancer’s picture

Example from user.admin.inc

/**
 * Preprocess variables for user-admin-roles template.
 *
 * @param $variables
 *   An associative array containing:
 *   - form: A render element representing the form.
 *
 * @ingroup themeable
 */
star-szr’s picture

In #1898460-4: taxonomy.module - Convert PHPTemplate templates to Twig we seem to have come up with a new option…

e.

/**
 * Preprocess variables for the item list template.
 */

Any objections? Or do we think plural "templates" makes sense when taking template suggestions into account?

I'm going to be going through the sandbox to try and make these a bit more consistent, and (after talking to @jenlampton in IRC) adding @see references from the preprocess function to the .html.twig template file, i.e.

/**
 * Preprocess variables for the page template.
 *
 * …
 *
 * @see drupal_render_page()
 * @see template_process_page()
 * @see page.html.twig
 */
c4rl’s picture

One thing of note here is how the preprocess layer may change as part of the execution stack. 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."

So, might it be applicable to use the word "prepare" instead? This really gets to the core meaning of what happens here without invoking that this is literally "pre-processing."


/**
 * Prepare variables for item list template.
 */

UPDATE: Fixed typo in codeblock above, where I left "preprocess" instead of "prepare."

Let me know if I'm bikeshedding. :)

steveoliver’s picture

You probably meant

/**
  * Prepare variables for item list template.
  */

?

Sounds better, and maybe bikesheddy if we're not at the same time making the change in naming of 'preprocess', but at least it helps us clarify what we're doing at this point.

+1

star-szr’s picture

I like prepare as well. I think this type of change should probably go through the core documentation queue, so we can come up with a standard on documenting preprocess functions.

If we go with "Prepare" for the preprocess functions, what about process functions? Or have we decided that process is going away?

Looking at http://drupal.org/node/1354#functions again, the current standards would give us something closer to "Preprocesses variables for…" or "Prepares variables for…".

Core documentation issue just created:
#1913208: [policy] Standardize template preprocess function documentation

star-szr’s picture

Status: Active » Closed (duplicate)

Closing this issue, the core issue is ready for review:
#1913208: [policy] Standardize template preprocess function documentation