Update all preprocess docblocks

[jenlampton]

Initial PR for this issue: backdrop/backdrop#3113

The documentation we use for preprocess functions is inconsistent all over core. Drupal 8 adopted a new standard. Below are two examples of the documentation I'm proposing for Backdrop.

1. When there are only a few variables (5 or fewer) provided to the template we should list them all in the docs for the preprocess function. For example:

/**
 * Prepares variables for block templates.
 *
 * @param $variables
 *   An array containing (but not limited to) the following:
 *   - content: The actual content of the block.
 *   - block: The block object being displayed.
 *
 * @see block.tpl.php
 */
function template_preprocess_block(&$variables) {

2. When there are a lot of variables (6 or more) provided to the template (node, for example) we can point people to the template file where all available default variables should be listed. For example:

/**
 * Prepares variables for node templates.
 *
 * Most themes use their own copy of node.tpl.php. The default is located at
 * "core/modules/node/node.tpl.php". The full list of variables is documented
 * in that file.
 *
 * @param $variables
 *   An array containing, but not imited to, the following:
 *   - node: Full node entity. Contains data that may not be safe.
 *   - view_mode: View mode; for example, "full", or "teaser".
 *
 * @see node.tpl.php
 */
function template_preprocess_node(&$variables) {

I think we need to define the line between 'a few' and 'a TON'... 🙂

[ps23Rick]

I could take a stab at this if someone would be so kind as to point me in the right direction as a good starting point or the rough scope of what needs to be tackled. Thx!

[jenlampton]

I think we need to define the line between 'a few' and 'a TON'...

How about 5/6? If there are 5 variables or less they get documented in the preprocess docblock, and if there are more than 5, we point to the primary template file docblock instead.

a good starting point or the rough scope of what needs to be tackled

I would do a search through the codebase for _preprocess_ to get a rough idea of how many instances there are of this type of docblock. Each one will need to be reviewed, and if it is not in line with the standard noted in this issue, updated.

Let's look at core/themes/seven/template.php For example. In here, I see:

/**
 * Implements hook_preprocess_page().
 */
function seven_preprocess_page(&$variables) {
  // Add the OpenSans font from core on every page of the site.
  backdrop_add_library('system', 'opensans', TRUE);
}

This would need to be changed to:

/**
 * Prepares variables for page templates.
 *
 * Many themes provide their own copy of page.tpl.php. The default is located at
 * "core/modules/system/page.tpl.php". The full list of variables is documented
 * in that file.
 *
 * @param $variables
 *   An array containing (but not limited to) the following:
 *   - page: The rendered page content, as output from Layout module.
 *   - page_bottom: Final closing markup from any modules that have altered the
 *   page. This variable should always be output last, after all other dynamic
 *   content.
 * 
 * @see page.tpl.php
 */
function seven_preprocess_page(&$variables) {
  // Add the OpenSans font from core on every page of the site.
  backdrop_add_library('system', 'opensans', TRUE);
}

There are a lot of these. It might make the most sense to make separate PRs.

[ps23Rick]

I can certainly take a look around and at least see how much there is to tackle. When you suggest making separate PRs, are you talking one per file/module or something different? I'm assuming one per file/module but perhaps I'm wrong..

[jenlampton]

When you suggest making separate PRs, are you talking one per file/module or something different?

That will depend on how much there is to tackle :) If there's only one function per module you may want to combine a few of those, but yeah something like one per file/module.

[ps23Rick]

How about I scrounge up a few files and make the appropriate changes (or what I perceive them to be) and put up a review to see if they meet your looking for and we can go from there..?

[jenlampton]

That would be wonderful :)

[ps23Rick]

Ok.. I've checked in one template file and created a PR to review it. I'm seeking feedback on whether further changes are desired or whether to continue, etc.. Thanks!

[jenlampton]

@ps23Rick could you please add a link here to the PR you created? Thanks!

[ps23Rick]

I just did.. Let me know what you think plz..