#718860 by djac, jhodgdon: Fixes to hook_theme() documentation.

modules/system/system.api.php

@@ -1587,91 +1587,92 @@ function hook_permission() {
 /**
  * Register a module (or theme's) theme implementations.
  *
- * Modules and themes implementing this return an array of arrays. The key
- * to each sub-array is the internal name of the hook, and the array contains
- * info about the hook. Each array may contain the following items:
- *
- * - variables: (required if "render element" not present) An array of
- *   variables that this theme hook uses. This value allows the theme layer to
- *   properly utilize templates. Each array key represents the name of the
- *   variable and the value will be used as the default value if it is not given
- *   when theme() is called. Template implementations receive these arguments as
- *   variables in the template file. Function implementations are passed this
- *   array data in the $variables parameter.
- * - render element: (required if "variables" not present) A string that is the
- *   name of the sole renderable element to pass to the theme function. The
- *   string represents the name of the "variable" that will hold the renderable
- *   array inside any optional preprocess or process functions. Cannot be used
- *   with the "variables" item; only one or the other, not both, can be present
- *   in a hook's info array.
- * - file: The file the implementation resides in. This file will be included
- *   prior to the theme being rendered, to make sure that the function or
- *   preprocess function (as needed) is actually loaded; this makes it possible
- *   to split theme functions out into separate files quite easily.
- * - path: Override the path of the file to be used. Ordinarily the module or
- *   theme path will be used, but if the file will not be in the default path,
- *   include it here. This path should be relative to the Drupal root
- *   directory.
- * - template: If specified, this theme implementation is a template, and this
- *   is the template file <b>without an extension</b>. Do not put .tpl.php
- *   on this file; that extension will be added automatically by the default
- *   rendering engine (which is PHPTemplate). If 'path', above, is specified,
- *   the template should also be in this path.
- * - function: If specified, this will be the function name to invoke for this
- *   implementation. If neither file nor function is specified, a default
- *   function name will be assumed. For example, if a module registers
- *   the 'node' theme hook, 'theme_node' will be assigned to its function.
- *   If the chameleon theme registers the node hook, it will be assigned
- *   'chameleon_node' as its function.
- * - pattern: A regular expression pattern to be used to allow this theme
- *   implementation to have a dynamic name. The convention is to use __ to
- *   differentiate the dynamic portion of the theme. For example, to allow
- *   forums to be themed individually, the pattern might be: 'forum__'. Then,
- *   when the forum is themed, call: <code>theme(array('forum__' . $tid, 'forum'),
- *   $forum)</code>.
- * - preprocess functions: A list of functions used to preprocess this data.
- *   Ordinarily this won't be used; it's automatically filled in. By default,
- *   for a module this will be filled in as template_preprocess_HOOK. For
- *   a theme this will be filled in as phptemplate_preprocess and
- *   phptemplate_preprocess_HOOK as well as themename_preprocess and
- *   themename_preprocess_HOOK.
- * - override preprocess functions: Set to TRUE when a theme does NOT want the
- *   standard preprocess functions to run. This can be used to give a theme
- *   FULL control over how variables are set. For example, if a theme wants
- *   total control over how certain variables in the page.tpl.php are set,
- *   this can be set to true. Please keep in mind that when this is used
- *   by a theme, that theme becomes responsible for making sure necessary
- *   variables are set.
- * - type: (automatically derived) Where the theme hook is defined:
- *   'module', 'theme_engine', or 'theme'.
- * - theme path: (automatically derived) The directory path of the theme or
- *   module, so that it doesn't need to be looked up.
- *
  * The following parameters are all optional.
  *
- * @param $existing
+ * @param array $existing
  *   An array of existing implementations that may be used for override
  *   purposes. This is primarily useful for themes that may wish to examine
  *   existing implementations to extract data (such as arguments) so that
  *   it may properly register its own, higher priority implementations.
  * @param $type
- *   What 'type' is being processed. This is primarily useful so that themes
- *   tell if they are the actual theme being called or a parent theme.
- *   May be one of:
- *     - module: A module is being checked for theme implementations.
- *     - base_theme_engine: A theme engine is being checked for a theme which is a parent of the actual theme being used.
- *     - theme_engine: A theme engine is being checked for the actual theme being used.
- *     - base_theme: A base theme is being checked for theme implementations.
- *     - theme: The actual theme in use is being checked.
+ *   Whether a theme, module, etc. is being processed. This is primarily useful
+ *   so that themes tell if they are the actual theme being called or a parent
+ *   theme. May be one of:
+ *   - 'module': A module is being checked for theme implementations.
+ *   - 'base_theme_engine': A theme engine is being checked for a theme that is
+ *     a parent of the actual theme being used.
+ *   - 'theme_engine': A theme engine is being checked for the actual theme
+ *     being used.
+ *   - 'base_theme': A base theme is being checked for theme implementations.
+ *   - 'theme': The actual theme in use is being checked.
  * @param $theme
- *   The actual name of theme that is being being checked (mostly only useful for
- *   theme engine).
+ *   The actual name of theme, module, etc. that is being being processed.
  * @param $path
  *   The directory path of the theme or module, so that it doesn't need to be
  *   looked up.
  *
- * @return
- *   A keyed array of theme hooks.
+ * @return array
+ *   An associative array of theme hook information. The keys on the outer
+ *   array are the internal names of the hooks, and the values are arrays
+ *   containing information about the hook. Each array may contain the
+ *   following elements:
+ *   - variables: (required if "render element" not present) An array of
+ *     variables that this theme hook uses. This value allows the theme layer to
+ *     properly utilize templates. Each array key represents the name of the
+ *     variable and the value will be used as the default value if it is not
+ *     given when theme() is called. Template implementations receive these
+ *     arguments as variables in the template file. Function implementations
+ *     are passed this array data in the $variables parameter.
+ *   - render element: (required if "variables" not present) A string that is
+ *     the name of the sole renderable element to pass to the theme function.
+ *     The string represents the name of the "variable" that will hold the
+ *     renderable array inside any optional preprocess or process functions.
+ *     Cannot be used with the "variables" item; only one or the other, not
+ *     both, can be present in a hook's info array.
+ *   - file: The file the implementation resides in. This file will be included
+ *     prior to the theme being rendered, to make sure that the function or
+ *     preprocess function (as needed) is actually loaded; this makes it
+ *     possible to split theme functions out into separate files quite easily.
+ *   - path: Override the path of the file to be used. Ordinarily the module or
+ *     theme path will be used, but if the file will not be in the default path,
+ *     include it here. This path should be relative to the Drupal root
+ *     directory.
+ *   - template: If specified, this theme implementation is a template, and this
+ *     is the template file without an extension. Do not put .tpl.php on this
+ *     file; that extension will be added automatically by the default rendering
+ *     engine (which is PHPTemplate). If 'path', above, is specified, the
+ *     template should also be in this path.
+ *   - function: If specified, this will be the function name to invoke for this
+ *     implementation. If neither file nor function is specified, a default
+ *     function name will be assumed. For example, if a module registers
+ *     the 'node' theme hook, 'theme_node' will be assigned to its function.
+ *     If the chameleon theme registers the node hook, it will be assigned
+ *     'chameleon_node' as its function.
+ *   - pattern: A regular expression pattern to be used to allow this theme
+ *     implementation to have a dynamic name. The convention is to use __ to
+ *     differentiate the dynamic portion of the theme. For example, to allow
+ *     forums to be themed individually, the pattern might be: 'forum__'. Then,
+ *     when the forum is themed, call:
+ *     @code
+ *     theme(array('forum__' . $tid, 'forum'), $forum)
+ *     @endcode
+ *   - preprocess functions: A list of functions used to preprocess this data.
+ *     Ordinarily this won't be used; it's automatically filled in. By default,
+ *     for a module this will be filled in as template_preprocess_HOOK. For
+ *     a theme this will be filled in as phptemplate_preprocess and
+ *     phptemplate_preprocess_HOOK as well as themename_preprocess and
+ *     themename_preprocess_HOOK.
+ *   - override preprocess functions: Set to TRUE when a theme does NOT want the
+ *     standard preprocess functions to run. This can be used to give a theme
+ *     FULL control over how variables are set. For example, if a theme wants
+ *     total control over how certain variables in the page.tpl.php are set,
+ *     this can be set to true. Please keep in mind that when this is used
+ *     by a theme, that theme becomes responsible for making sure necessary
+ *     variables are set.
+ *   - type: (automatically derived) Where the theme hook is defined:
+ *     'module', 'theme_engine', or 'theme'.
+ *   - theme path: (automatically derived) The directory path of the theme or
+ *     module, so that it doesn't need to be looked up.
  */
 function hook_theme($existing, $type, $theme, $path) {
   return array(