? hook_theme_registry_alter-docs-259116-1.patch
? hook_theme_registry_alter-docs-259116-4.patch
? hook_theme_registry_alter-docs-259116-5.patch
Index: core.php
===================================================================
RCS file: /cvs/drupal-contrib/contributions/docs/developer/hooks/core.php,v
retrieving revision 1.177
diff -u -p -r1.177 core.php
--- core.php	16 May 2008 03:03:45 -0000	1.177
+++ core.php	16 May 2008 04:47:01 -0000
@@ -1437,10 +1437,12 @@ function hook_taxonomy($op, $type, $arra
  * 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:
  *
- * - 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.
+ * - arguments: (required) An array of arguments that this theme hook uses. This
+ *   value allows the theme layer to properly utilize templates. The
+ *   array keys represent the name of the variable, and the value will be
+ *   used as the default value if not specified to the theme() function.
+ *   These arguments must be in the same order that they will be given to
+ *   the theme() function.
  * - 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
@@ -1450,18 +1452,16 @@ function hook_taxonomy($op, $type, $arra
  *   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.
+ * - 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.
  * - 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.
- * - arguments: An array of arguments that this theme hook uses. This is
- *   required so that the theme layer may properly utilize templates. The
- *   array keys represent the name of the variable, and the value will be
- *   used as the default value if not specified to the theme() function.
- *   These arguments must be in the same order that they will be given to
- *   the theme() 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
@@ -1481,6 +1481,12 @@ function hook_taxonomy($op, $type, $arra
  *   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.
+ * - theme paths: (automatically derived) An array of template suggestions where
+ *   .tpl.php files related to this theme hook may be found.
  *
  * @param $existing
  *   An array of existing implementations that may be used for override
@@ -1531,15 +1537,37 @@ function hook_theme() {
  *
  * The theme registry stores information about all available theme hooks,
  * including which callback functions those hooks will call when triggered,
- * what template files are exposed by these hooks, and so on. Any of this
- * information may be modified by hook_theme_registry_alter().
+ * what template files are exposed by these hooks, and so on.
  *
- * Note that this hook is only executed as the theme cache is re-built.
- * Changes here will not be visible until the next cache clear.
+ * The $theme_registry array is keyed by theme hook name, and contains the
+ * information returned from hook_theme(), as well as additional properties
+ * added by _theme_process_registry().
+ *
+ * For example:
+ * @code
+ *  $theme_registry['user_profile'] = array(
+ *    'arguments' => array(
+ *      'account' => NULL,
+ *    ),
+ *    'template' => 'modules/user/user-profile',
+ *    'file' => 'modules/user/user.pages.inc',
+ *    'type' => 'module',
+ *    'theme path' => 'modules/user',
+ *    'theme paths' => array(
+ *      0 => 'modules/user',
+ *    ),
+ *    'preprocess functions' => array(
+ *      0 => 'template_preprocess',
+ *      1 => 'template_preprocess_user_profile',
+ *     ),
+ *   )
+ * );
+ * @endcode
  *
  * @param $theme_registry
- *   The entire cache of theme registry information returned from hook_theme().
+ *   The entire cache of theme registry information, post-processing.
  * @see hook_theme()
+ * @see _theme_process_registry()
  */
 function hook_theme_registry_alter(&$theme_registry) {
   // Kill the next/previous forum topic navigation links.