From a7746dba86d18bc9c9d1dad452d74dc909d88e7a Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Tue, 30 Jul 2013 06:05:47 -0700
Subject: Issue #2031319 by jlindsey15, pplantinga, thedavidmeister, Kingdutch,
 Kiphaas7: Document that theme() should really be called via drupal_render().

---
 includes/theme.inc | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

(limited to 'includes')

diff --git a/includes/theme.inc b/includes/theme.inc
index f80757e6e..5ae0fea20 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -869,11 +869,17 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) {
 /**
  * Generates themed output.
  *
- * All requests for themed output must go through this function. It examines
- * the request and routes it to the appropriate
+ * All requests for themed output must go through this function (however,
+ * calling the theme() function directly is 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().
+ *
  * @section sec_theme_hooks Theme Hooks
  * Most commonly, the first argument to this function is the name of the theme
  * hook. For instance, to theme a taxonomy term, the theme hook name is
@@ -997,6 +1003,7 @@ function drupal_find_base_themes($themes, $key, $used_keys = array()) {
  * @return
  *   An HTML string representing the themed output.
  *
+ * @see drupal_render()
  * @see themeable
  * @see hook_theme()
  * @see template_preprocess()
-- 
cgit v1.2.3