Index: includes/theme.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/theme.inc,v
retrieving revision 1.627
diff -u -r1.627 theme.inc
--- includes/theme.inc	3 Jan 2011 08:02:11 -0000	1.627
+++ includes/theme.inc	14 Jan 2011 03:15:33 -0000
@@ -930,14 +930,33 @@
 }
 
 /**
- * Return the path to the current themed element.
+ * Returns a path to the theme or module with the current theming function.
  *
- * It can point to the active theme or the module handling a themed implementation.
- * For example, when invoked within the scope of a theming call it will depend
- * on where the theming function is handled. If implemented from a module, it
- * will point to the module. If implemented from the active theme, it will point
- * to the active theme. When called outside the scope of a theming call, it will
- * always point to the active theme.
+ * This function usually returns the path to a "theming function". The meaning
+ * of "theming function" depends on whether the theme() call is using a theme
+ * function or a theme template.
+ *
+ * In calls to theme() that result in a theme function being used, the theme
+ * function that is actually called is the "theming function". So, this could be
+ * a theme_HOOK() reference implementation from a module, a THEME_HOOK()
+ * override from a base theme or the active theme, or a more specific override
+ * from a template suggestion, such as THEME_HOOK__type1().
+ *
+ * In calls to theme() that result in a template file being used, the "theming
+ * function" is the process or preprocess function that is called to set up the
+ * variables (with precidence given to the process function, if one exists). So,
+ * the "theming function" could be the template_process_HOOK() reference
+ * implementation from a module, a THEME_process_HOOK() override from a base
+ * theme or the active theme, etc. Note that the "theming function" may not be
+ * part of the same theme that contains the template file being used for
+ * theming in this case.
+ *
+ * @return
+ *   Outside of the scope of a call to theme(), this function returns the path
+ *   to the default theme, or to the custom theme for the current page. Within
+ *   the scope of a call to theme(), this function returns the path to the
+ *   module or theme containing the "theming function" (see above) that is
+ *   called for the element being themed.
  */
 function path_to_theme() {
   global $theme_path;