Issue #1253828 by sven.lauer: Fixed drupal_render() doc should explain what 'child' means.

1 files changed, 16 insertions, 7 deletions

diff --git a/includes/common.inc b/includes/common.inc
index a94b011f1..bd7c6892b 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -5519,15 +5519,24 @@ function drupal_render_page($page) {
  *
  * Recursively iterates over each of the array elements, generating HTML code.
  *
- * HTML generation is controlled by two properties containing theme functions,
- * #theme and #theme_wrappers.
+ * Renderable arrays have two kinds of key/value pairs: properties and
+ * children. Properties have keys starting with '#' and their values influence
+ * how the array will be rendered. Children are all elements whose keys do not
+ * start with a '#'. Their values should be renderable arrays themselves,
+ * which will be rendered during the rendering of the parent array. The markup
+ * provided by the children is typically inserted into the markup generated by
+ * the parent array.
+ *
+ * HTML generation for a renderable array, and the treatment of any children,
+ * is controlled by two properties containing theme functions, #theme and
+ * #theme_wrappers.
  *
  * #theme is the theme function called first. If it is set and the element has
- * any children, they have to be rendered there. For elements that are not
- * allowed to have any children, e.g. buttons or textfields, it can be used to
- * render the element itself. If #theme is not present and the element has
- * children, they are rendered and concatenated into a string by
- * drupal_render_children().
+ * any children, it is the responsibility of the theme function to render
+ * these children. For elements that are not allowed to have any children,
+ * e.g. buttons or textfields, the theme function can be used to render the
+ * element itself. If #theme is not present and the element has children, they
+ * are rendered and concatenated into a string by drupal_render_children().
  *
  * The #theme_wrappers property contains an array of theme functions which will
  * be called, in order, after #theme has run. These can be used to add further