function _theme_build_registry($theme, $base_theme, $theme_engine) {
  ... ...
}

foreach (module_implements(‘theme‘) as $module) {
  // 注意调用时$name=模块名称, $type=‘module‘, $theme=模块名称, $path=模块路径
  _theme_process_registry($cache, $module, ‘module‘, $module, drupal_get_path(‘module‘, $module));
}

// Process each base theme.
foreach ($base_theme as $base) {
  // If the base theme uses a theme engine, process its hooks.
  $base_path = dirname($base->filename);
  if ($theme_engine) {
    // 注意调用时$name=theme engine name, $type=‘base_theme_engine‘, $theme=base theme name, $path=base theme path
    // 对theme engine调用时，$theme都是对应的theme name, $path都是对应的theme path
    _theme_process_registry($cache, $theme_engine, ‘base_theme_engine‘, $base->name, $base_path);
  }
  // 注意调用时$name=base theme name, $type=‘base_theme‘, $theme=base theme name, $path=base theme path
  _theme_process_registry($cache, $base->name, ‘base_theme‘, $base->name, $base_path);
}

// And then the same thing, but for the theme.
if ($theme_engine) {
  // 注意调用时$name=theme engine name, $type=‘theme_engine‘, $theme=theme name, $path=theme path
  // 对theme engine调用时，$theme都是对应的theme name, $path都是对应的theme path
  _theme_process_registry($cache, $theme_engine, ‘theme_engine‘, $theme->name, dirname($theme->filename));
}

// Finally, hooks provided by the theme itself.
// 注意调用时$name=theme name, $type=‘theme‘, $theme=theme name, $path=theme path
_theme_process_registry($cache, $theme->name, ‘theme‘, $theme->name, dirname($theme->filename));

function _theme_process_registry(&$cache, $name, $type, $theme, $path) {
  ... ... // 注意这里的参数$cache是传址的
}

$variable_process_phases = array(
  ‘preprocess functions‘ => ‘preprocess‘,
  ‘process functions‘    => ‘process‘,
);

$hook_defaults = array(
  ‘variables‘ => TRUE,
  ‘render element‘ => TRUE,
  ‘pattern‘ => TRUE,
  ‘base hook‘ => TRUE,
);

// Invoke the hook_theme() implementation, process what is returned, and
// merge it into $cache.
$function = $name . ‘_theme‘;
if (function_exists($function)) {
  $result = $function($cache, $type, $theme, $path);
  foreach ($result as $hook => $info) {
    // When a theme or engine overrides a module‘s theme function
    // $result[$hook] will only contain key/value pairs for information being
    // overridden.  Pull the rest of the information from what was defined by
    // an earlier hook.

    // Fill in the type and path of the module, theme, or engine that
    // implements this theme function.
    $result[$hook][‘type‘] = $type; 
    $result[$hook][‘theme path‘] = $path;

    // 注意这里的type和theme path，这和传入的参数密切相关
    // 当type=module时，theme path=module path
    // 当type=base theme engine时，因为传入的是base theme path，所以theme path=base theme path
    // 当type=base them时，theme path=base theme path
    // 当type=theme engine时，因为传入的是current theme path，所以theme path=current theme path
    // 当type=theme时，theme path=current theme path

    // If function and file are omitted, default to standard naming
    // conventions.
    if (!isset($info[‘template‘]) && !isset($info[‘function‘])) {
      $result[$hook][‘function‘] = ($type == ‘module‘ ? ‘theme_‘ : $name . ‘_‘) . $hook;
    }

    // 在hook_theme()定义theme hook时，一般会设置template或者function
    // 如果两者都没有设置，则默认地type=module时为theme_$hook()，或者$name_$hook()
    // 例如type=theme，则可能是bartik_cool_messages()
    // 或者type=theme engine，则可能是phptemplate_cool_engine()

    if (isset($cache[$hook][‘includes‘])) {
      $result[$hook][‘includes‘] = $cache[$hook][‘includes‘];
    }

    // $cache[$hook]是什么意思？
    // 在后面会看到这样一句代码：$cache = $result + $cache;
    // $cache合并了当前的hook_theme()结果$result，并确保$result优先$cache
    // 举例来说，可能在practice模块中定义了cool_messsages,
    // 当_theme_process_registry()在type=module被执行完成后，$cache就应该有了cool_messages。
    // 后面的bartik又修改了cool_messages的定义，当type=theme执行完成后，
    // $cache的就是两者合并后的结果，并且后面定义的优先于前面定义的。

    // If the theme implementation defines a file, then also use the path
    // that it defined. Otherwise use the default path. This allows
    // system.module to declare theme functions on behalf of core .include
    // files.
    if (isset($info[‘file‘])) {
      $include_file = isset($info[‘path‘]) ? $info[‘path‘] : $path;
      $include_file .= ‘/‘ . $info[‘file‘];
      include_once DRUPAL_ROOT . ‘/‘ . $include_file;
      $result[$hook][‘includes‘][] = $include_file;
    }

    // 可以定义一个专门的theme function file，用$info[‘file‘]说明
    // 这个theme function file可能不属于当前模块，例如可能是system模块用到core模块里面的文件，
    // 这时候需要用$info[‘path‘]说明这个theme function file所在的目录

    // If the default keys are not set, use the default values registered
    // by the module.
    if (isset($cache[$hook])) {
      $result[$hook] += array_intersect_key($cache[$hook], $hook_defaults);
    }

    // The following apply only to theming hooks implemented as templates.
    if (isset($info[‘template‘])) {
      // Prepend the current theming path when none is set.
      if (!isset($info[‘path‘])) {
        // 将template转成完整路径
        $result[$hook][‘template‘] = $path . ‘/‘ . $info[‘template‘];
      }
    }

    // Allow variable processors for all theming hooks, whether the hook is
    // implemented as a template or as a function.
    foreach ($variable_process_phases as $phase_key => $phase) {
      // Check for existing variable processors. Ensure arrayness.
      if (!isset($info[$phase_key]) || !is_array($info[$phase_key])) {
        $info[$phase_key] = array();
        $prefixes = array();
        if ($type == ‘module‘) {
          // Default variable processor prefix.
          $prefixes[] = ‘template‘;
          // Add all modules so they can intervene with their own variable
          // processors. This allows them to provide variable processors even
          // if they are not the owner of the current hook.
          $prefixes += module_list();
        }
        elseif ($type == ‘theme_engine‘ || $type == ‘base_theme_engine‘) {
          // Theme engines get an extra set that come before the normally
          // named variable processors.
          $prefixes[] = $name . ‘_engine‘;
          // The theme engine registers on behalf of the theme using the
          // theme‘s name.
          $prefixes[] = $theme;
        }
        else {
          // This applies when the theme manually registers their own variable
          // processors.
          $prefixes[] = $name;
        }
        foreach ($prefixes as $prefix) {
          // Only use non-hook-specific variable processors for theming hooks
          // implemented as templates. See theme().
          if (isset($info[‘template‘]) && function_exists($prefix . ‘_‘ . $phase)) {
            $info[$phase_key][] = $prefix . ‘_‘ . $phase;
          }
          if (function_exists($prefix . ‘_‘ . $phase . ‘_‘ . $hook)) {
            $info[$phase_key][] = $prefix . ‘_‘ . $phase . ‘_‘ . $hook;
          }
        }

        // variable processor，变量处理器，这是一个数组
        // 变量处理器分两种：preprocess function和皮肉process function
        // 当type=module时，按照下列顺序查找（以cool_messages为例）：
        //       template_preprocess()
        //       template_preprocess_cool_messages()
        //       moduleA_preprocess()
        //       moduleA_preprocess_cool_messages()
        //       ... ...
        //       moduleZ_preprocess()
        //       moduleZ_preprocess_cool_messages()
        //       ---
        //       template_process()
        //       template_process_cool_messages()
        //       moduleA_process()
        //       moduleA_process_cool_messages()
        //       ... ...
        //       moduleZ_process()
        //       moduleZ_process_cool_messages()
        //
        // 当type=theme_engine/base_theme_engine时，按照下列顺序查找：
        //       phptemplate_engine_preprocess()
        //       phptemplate_engine_preprocess_cool_messages()
        //       bartik_preprocess()
        //       bartik_preprocess_cool_messages()
        //       ---
        //       phptemplate_engine_process()
        //       phptemplate_engine_process_cool_messages()
        //       bartik_process()
        //       bartik_process_cool_messages()
        //
        // 当type=theme/base_theme时，按照下列顺序查找：
        //       bartik_preprocess()
        //       bartik_preprocess_cool_messages()
        //       ---
        //       bartik_process()
        //       bartik_process_cool_messages()

      }
      // Check for the override flag and prevent the cached variable
      // processors from being used. This allows themes or theme engines to
      // remove variable processors set earlier in the registry build.
      if (!empty($info[‘override ‘ . $phase_key])) {
        // Flag not needed inside the registry.
        unset($result[$hook][‘override ‘ . $phase_key]);
        // 色泽override preprocess functions这样的参数，
        // 可以忽略其它情况下的变量处理器
      }
      elseif (isset($cache[$hook][$phase_key]) && is_array($cache[$hook][$phase_key])) {
        $info[$phase_key] = array_merge($cache[$hook][$phase_key], $info[$phase_key]);
        // 这里将$cache[$hook][$phase_key]和$info[$phase_key]做了合并，
        // 也就是说可能出现这样的情况：
        //       practice_preprocess()/practice_preproces_cool_messages()    模块practice的缺省处理器
        //       other_preproces_cool_messages()                             模块other定义的cool_messages处理器
        //       phptemplate_engine_preprocess_cool_messages()               主题引擎定义的cool_messages处理器
        //       bartik_preprocess_cool_message()                            主题bartik定义的cool_messages处理器
        //       sub_bartik_preprocess_cool_message()                        主题sub_bartik定义的cool_messages处理器
        // 这些变量处理器是没有顺序的，这一点要特别注意
      }
      $result[$hook][$phase_key] = $info[$phase_key];
    }
  }

  // Merge the newly created theme hooks into the existing cache.
  // 合并$result到$cache，这一句代码很重要
  // _theme_build_registry()执行完成后，$cache就是最后的theme registry
  $cache = $result + $cache;
}

// $result是hook_theme()返回的结果
// phptemplate_theme()做了两件事情：
// 一是搜索get_defined_functions()中所有的theme function，
// 二是搜索主题目录下所有以.tpl.php结尾的theme template，
// 然后返回到$result，再保存到$cache.
// 例如，theme目录中可以存在一个cool_sideleft.tpl.php这样一个theme template，
// 不需要用hook_theme()定义这个theme hook，phptemplate会自动搜索这个theme template注册到$cache。
// 
// phptemplate执行在前，theme执行在后，
// 当theme执行时，$cache已经包含了them中定义所有theme function和theme template。
// 这时候，可以在theme定义变量处理器，例如bartik_preprocess_cool_sideleft()。
// 执行下面的代码可以将bartik_preprocess_cool_sideleft()关联到cool_sideleft。

// Let themes have variable processors even if they didn‘t register a
// template.
if ($type == ‘theme‘ || $type == ‘base_theme‘) {
  foreach ($cache as $hook => $info) {
    // Check only if not registered by the theme or engine.
    if (empty($result[$hook])) {
      foreach ($variable_process_phases as $phase_key => $phase) {
        if (!isset($info[$phase_key])) {
          $cache[$hook][$phase_key] = array();
        }
        // Only use non-hook-specific variable processors for theming hooks
        // implemented as templates. See theme().
        if (isset($info[‘template‘]) && function_exists($name . ‘_‘ . $phase)) {
          $cache[$hook][$phase_key][] = $name . ‘_‘ . $phase;
        }
        if (function_exists($name . ‘_‘ . $phase . ‘_‘ . $hook)) {
          $cache[$hook][$phase_key][] = $name . ‘_‘ . $phase . ‘_‘ . $hook;
          $cache[$hook][‘theme path‘] = $path;
        }
        // Ensure uniqueness.
        $cache[$hook][$phase_key] = array_unique($cache[$hook][$phase_key]);
      }
    }
  }
}

function practice_theme() {
    return array(
        ‘cool_breadcrumbs‘ => array(
            ‘render element‘ => ‘breadcrumbs‘,
            ‘function‘ => ‘practice_cool_breadcrumbs‘,
        ),
        ‘cool_messages‘ => array(
            ‘render element‘ => ‘messages‘,
            ‘template‘ => ‘cool_messages‘,
        ),
    );
}

function practice_cool_breadcrumbs($variables) {
  return ‘<div>Demo Breadcrumbs</div>‘;
}

<?php
// sites/all/modules/practice/cool_messages.tpl.php
print ‘<div>Demo Messages</div>‘;

$result = array(
  ‘cool_breadcrumbs‘ => array(
    ‘render element‘ => ‘breadcrumbs‘,
    ‘function‘ => ‘practice_cool_breadcrumbs‘,
    ‘type‘ => ‘module‘,
    ‘theme path‘ => ‘sites/all/modules/practice‘,
    ‘preprocess functions‘ => array(),
    ‘process functions‘ => array(),
  ),
  ‘cool_messages‘ => array(
    ‘render element‘ => ‘messages‘,
    ‘template‘ => ‘sites/all/modules/practice/cool_messages‘, // template转成了完整路径
    ‘type‘ => ‘module‘,
    ‘theme path‘ => ‘sites/all/modules/practice‘,
    ‘preprocess functions‘ => array( // 用template实现的theme hook，默认的会加上template_preprocess/process()
      0 => ‘template_preprocess‘, 
    ),
    ‘process functions‘ => array(
      0 => ‘template_process‘,
    ),
  ),
);

function practice_preprocess(&$variables, $hook) { ... }
function practice_process(&$variables, $hook) { ... }

$result = array(
  ‘cool_breadcrumbs‘ => array(
    ... ...
    ‘preprocess functions‘ => array(), // 不带theme hook名称的变量处理器不适用于function
    ‘process functions‘ => array(),
  ),
  ‘cool_messages‘ => array(
    ... ...
    ‘preprocess functions‘ => array(
      0 => ‘template_preprocess‘, 
      1 => ‘practice_preprocess‘, // 不带theme hook名称的变量处理器只针对template
    ),
    ‘process functions‘ => array(
      0 => ‘template_process‘, 
      1 => ‘practice_preprocess‘,
    ),
  ),
);

function practice_preprocess_cool_breadcrumbs(&$variables, $hook) { ... }

$result = array(
  ‘cool_breadcrumbs‘ => array(
    ‘preprocess functions‘ => array(
      0 => ‘practice_preprocess_cool_breadcrumbs‘, // 带名称的处理器只适用于指定名称的theme hook
    ),
    ‘process functions‘ => array(),
  ),
  ... ...
);

function other_preprocess(&$variables, $hook) { ... }
function other_preprocess_cool_messages(&$variables, $hook) { ... }

$result = array(
  ‘cool_messages‘ => array(
    ‘preprocess functions‘ => array(
      0 => ‘template_preprocess‘,
      1 => ‘other_preprocess‘,
      2 => ‘other_preprocess_cool_messages‘,
    ),
    ‘process functions‘ => array(
      0 => ‘template_process‘, 
    ),
  ),
);

if ($type == ‘theme‘ || $type == ‘base_theme‘) {
  foreach ($cache as $hook => $info) { // 只针对在$cache中已经注册过的theme hook
    // Check only if not registered by the theme or engine.
    if (empty($result[$hook])) { // empty($result[$hook])表明是没有在theme的hook_theme()钩子中定义
      foreach ($variable_process_phases as $phase_key => $phase) {
        if (!isset($info[$phase_key])) {
          $cache[$hook][$phase_key] = array();
        }
        // Only use non-hook-specific variable processors for theming hooks
        // implemented as templates. See theme().
        if (isset($info[‘template‘]) && function_exists($name . ‘_‘ . $phase)) {
          $cache[$hook][$phase_key][] = $name . ‘_‘ . $phase;
        }
        if (function_exists($name . ‘_‘ . $phase . ‘_‘ . $hook)) {
          $cache[$hook][$phase_key][] = $name . ‘_‘ . $phase . ‘_‘ . $hook;
          $cache[$hook][‘theme path‘] = $path;
        }
        // Ensure uniqueness.
        $cache[$hook][$phase_key] = array_unique($cache[$hook][$phase_key]);
      }
    }
  }
}

function bartik_preprocess_cool_messages(&$variables) { ... }

// _theme_process_registry($type=‘module‘, $name=‘practice‘)执行完毕后的$cache
$cache = array(
  ‘cool_messages‘ => array(
    ‘preprocess functions‘ => array(
      0 => ‘template_preprocess‘, 
    ),
    ‘process functions‘ => array(
      0 => ‘template_process‘,
    ),
  ),
);

// _theme_process_registry($type=‘theme‘, $name=‘bartik‘)执行完毕后的$cache
$cache = array(
  ‘cool_messages‘ => array(
    ‘preprocess functions‘ => array(
      0 => ‘template_preprocess‘,
      1 => ‘bartik_preprocess_cool_messages‘, // bartik中定义的处理器
    ),
    ‘process functions‘ => array(
      0 => ‘template_process‘,
    ),
  ),
);

function phptemplate_theme($existing, $type, $theme, $path) {
  $templates = drupal_find_theme_functions($existing, array($theme));
  $templates += drupal_find_theme_templates($existing, ‘.tpl.php‘, $path);
  return $templates;
}

function drupal_find_theme_functions($cache, $prefixes) {
  $implementations = array();
  $functions = get_defined_functions();

  // 查找以theme名称开头的theme functions
  // 注意这里只处理$cache中已注册的theme hook
  // $prefix指的是theme名称, 例如bartik

  foreach ($cache as $hook => $info) { 
    foreach ($prefixes as $prefix) { 

      // Find theme functions that implement possible "suggestion" variants of
      // registered theme hooks and add those as new registered theme hooks.
      // The ‘pattern‘ key defines a common prefix that all suggestions must
      // start with. The default is the name of the hook followed by ‘__‘. An
      // ‘base hook‘ key is added to each entry made for a found suggestion,
      // so that common functionality can be implemented for all suggestions of
      // the same base hook. To keep things simple, deep hierarchy of
      // suggestions is not supported: each suggestion‘s ‘base hook‘ key
      // refers to a base hook, not to another suggestion, and all suggestions
      // are found using the base hook‘s pattern, not a pattern from an
      // intermediary suggestion.

      // 这里查找的是theme suggestion functions
      // 例如，在$cahce中已存在名为page的theme hook
      // 可以在theme中定义一系列的theme suggestion functions：
      //     bartik_page__node()
      //     bartik_page__node__1()
      //
      // theme suggestion会做为一个新的theme hook被注册，例如
      //     $cache[‘page__node__1‘] = ...
      //
      // theme suggesion hook的base hook被标记为$hook

      $pattern = isset($info[‘pattern‘]) ? $info[‘pattern‘] : ($hook . ‘__‘);
      if (!isset($info[‘base hook‘]) && !empty($pattern)) {
        $matches = preg_grep(‘/^‘ . $prefix . ‘_‘ . $pattern . ‘/‘, $functions[‘user‘]);
        if ($matches) {
          foreach ($matches as $match) {
            $new_hook = substr($match, strlen($prefix) + 1);
            $arg_name = isset($info[‘variables‘]) ? ‘variables‘ : ‘render element‘;
            $implementations[$new_hook] = array(
              ‘function‘ => $match,
              $arg_name => $info[$arg_name],
              ‘base hook‘ => $hook,
            );
          }
        }
      }

      // Find theme functions that implement registered theme hooks and include
      // that in what is returned so that the registry knows that the theme has
      // this implementation.

      // 如果存在bartik_page()函数，则覆盖hook_theme()定义的page实现
      //
      // 覆盖是在_theme_process_registry()处理的, $result是phptemplate_theme()返回的结果:
      // if (isset($cache[$hook])) {
      //  $result[$hook] += array_intersect_key($cache[$hook], $hook_defaults);
      // }

      if (function_exists($prefix . ‘_‘ . $hook)) {
        $implementations[$hook] = array(
          ‘function‘ => $prefix . ‘_‘ . $hook,
        );
      }
    }
  }

  return $implementations;
}

function drupal_find_theme_templates($cache, $extension, $path) {
  $implementations = array();

  // Collect paths to all sub-themes grouped by base themes. These will be
  // used for filtering. This allows base themes to have sub-themes in its
  // folder hierarchy without affecting the base themes template discovery.
  $theme_paths = array();
  foreach (list_themes() as $theme_info) {
    if (!empty($theme_info->base_theme)) {
      $theme_paths[$theme_info->base_theme][$theme_info->name] = dirname($theme_info->filename);
    }
  }
  foreach ($theme_paths as $basetheme => $subthemes) {
    foreach ($subthemes as $subtheme => $subtheme_path) {
      if (isset($theme_paths[$subtheme])) {
        $theme_paths[$basetheme] = array_merge($theme_paths[$basetheme], $theme_paths[$subtheme]);
      }
    }
  }
  global $theme;
  $subtheme_paths = isset($theme_paths[$theme]) ? $theme_paths[$theme] : array();

  // Escape the periods in the extension.
  $regex = ‘/‘ . str_replace(‘.‘, ‘\.‘, $extension) . ‘$/‘;
  // Get a listing of all template files in the path to search.
  $files = drupal_system_listing($regex, $path, ‘name‘, 0);

  // 在theme目录下查找所有以.tpl.php结尾的模板文件:
  //    page.tpl.php
  //    page__node.tpl.php
  //    page__node__1.tpl.php

  // Find templates that implement registered theme hooks and include that in
  // what is returned so that the registry knows that the theme has this
  // implementation.
  foreach ($files as $template => $file) {
    // Ignore sub-theme templates for the current theme.
    if (strpos($file->uri, str_replace($subtheme_paths, ‘‘, $file->uri)) !== 0) {
      continue;
    }
    // Chop off the remaining extensions if there are any. $template already
    // has the rightmost extension removed, but there might still be more,
    // such as with .tpl.php, which still has .tpl in $template at this point.
    if (($pos = strpos($template, ‘.‘)) !== FALSE) {
      $template = substr($template, 0, $pos);
    }
    // Transform - in filenames to _ to match function naming scheme
    // for the purposes of searching.
    $hook = strtr($template, ‘-‘, ‘_‘);
    if (isset($cache[$hook])) { 
      // 只处理在$cache中注册的theme hook
      // 如果存page.tpl.php模板, 则覆盖hook_theme()定义的page实现
      $implementations[$hook] = array(
        ‘template‘ => $template,
        ‘path‘ => dirname($file->uri),
      );
    }
  }

  // Find templates that implement possible "suggestion" variants of registered
  // theme hooks and add those as new registered theme hooks. See
  // drupal_find_theme_functions() for more information about suggestions and
  // the use of ‘pattern‘ and ‘base hook‘.
  $patterns = array_keys($files);
  foreach ($cache as $hook => $info) { // 循环处理在$cache中注册的theme hook
    $pattern = isset($info[‘pattern‘]) ? $info[‘pattern‘] : ($hook . ‘__‘);
    if (!isset($info[‘base hook‘]) && !empty($pattern)) {
      // Transform _ in pattern to - to match file naming scheme
      // for the purposes of searching.
      $pattern = strtr($pattern, ‘_‘, ‘-‘);

      // 这里查找的是theme suggestion templates
      // theme suggestion会做为一个新的theme hook被注册，例如
      //     $cache[‘page__node__1‘] = ...
      //
      // theme suggesion hook的base hook被标记为$hook

      $matches = preg_grep(‘/^‘ . $pattern . ‘/‘, $patterns);
      if ($matches) {
        foreach ($matches as $match) {
          $file = substr($match, 0, strpos($match, ‘.‘));
          // Put the underscores back in for the hook name and register this
          // pattern.
          $arg_name = isset($info[‘variables‘]) ? ‘variables‘ : ‘render element‘;
          $implementations[strtr($file, ‘-‘, ‘_‘)] = array(
            ‘template‘ => $file,
            ‘path‘ => dirname($files[$match]->uri),
            $arg_name => $info[$arg_name],
            ‘base hook‘ => $hook,
          );
        }
      }
    }
  }
  return $implementations;
}

function bartik_theme() {
  return array(
    ‘cool_sideleft‘ => array(
      ‘render element‘ => ‘sideleft‘,
      ‘template‘ => ‘cool_sideleft‘,
    ),
  );
}

function bartik_preprocess_cool_sideleft(&$variables) { ... }

$result = array(
  ‘cool_sideleft‘ => array(
    ‘render element‘ => ‘sideleft‘,
    ‘template‘ => ‘themes/bartik/cool_sideleft‘,
    ‘type‘ => ‘theme‘,
    ‘theme path‘ => ‘themes/bartik‘,
    ‘preprocess functions‘ => array(
      0 => ‘bartik_preprocess_cool_sideleft‘, // 没有template_preprocess(). 处理器要以bartik_开头。
    ),
    ‘process functions‘ => array(),
  ),
);