diff --git a/core/includes/theme.inc b/core/includes/theme.inc
index 81ecd11..9a23bb3 100644
--- a/core/includes/theme.inc
+++ b/core/includes/theme.inc
@@ -342,16 +342,21 @@ function list_themes($refresh = FALSE) {
 /**
  * Generates themed output.
  *
- * All requests for themed output must go through this function (however,
- * calling the _theme() function directly is very strongly discouraged - see
- * next paragraph). It examines the request and routes it to the appropriate
- * @link themeable theme function or template @endlink, by checking the theme
- * registry.
- *
- * Avoid calling this function directly. It is preferable to replace direct
- * calls to the _theme() function with calls to drupal_render() by passing a
- * render array with a #theme key to drupal_render(), which in turn calls
- * _theme().
+ * _theme() is an internal function. Do not call this function directly as it
+ * will prevent the following items from working correctly:
+ * - Render caching.
+ * - JavaScript and CSS asset attachment.
+ * - Pre / post render hooks.
+ * - Defaults provided by hook_element_info(), including attached assets.
+ * Instead, build a render array with a #theme key, and either return the
+ * array (where possible) or call drupal_render() to convert it to HTML.
+ *
+ * All requests for themed output must go through this function, which is
+ * invoked as part of the @link theme_render drupal_render() process @endlink.
+ * The appropriate theme function is indicated by the #theme property
+ * of a renderable array. _theme() examines the request and routes it to the
+ * appropriate @link themeable theme function or template @endlink, by checking
+ * the theme registry.
  *
  * @section sec_theme_hooks Theme Hooks
  * Most commonly, the first argument to this function is the name of the theme