Index: includes/common.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/common.inc,v
retrieving revision 1.1243
diff -u -r1.1243 common.inc
--- includes/common.inc	21 Oct 2010 11:58:19 -0000	1.1243
+++ includes/common.inc	21 Oct 2010 14:30:13 -0000
@@ -5476,13 +5476,17 @@
 }
 
 /**
- * Render and print an element.
+ * Render an element.
  *
  * This function renders an element using drupal_render(). The top level
- * element is always rendered even if hide() had been previously used on it.
+ * element is shown with show() before rendering, so it will always be rendered
+ * even if hide() had been previously used on it.
  *
- * Any nested elements are only rendered if they haven't been rendered before
- * or if they have been re-enabled with show().
+ * @param $element
+ *   The element to be rendered.
+ *
+ * @return
+ *   The rendered element.
  *
  * @see drupal_render()
  * @see show()
@@ -5503,6 +5507,21 @@
 /**
  * Hide an element from later rendering.
  *
+ * If you are using this on an element low in the element tree, call hide()
+ * before the first call to render() or drupal_render() on the containing
+ * element tree, or it will have no effect. The reason is that the first time
+ * you call drupal_render() on an element tree, drupal_render() marks each
+ * element in the tree with a #printed flag as it is rendered. Subsequent calls
+ * to drupal_render() will not traverse the tree below when a #printed flag is
+ * encountered. So if you use hide() on a low-level element, it will have no
+ * effect on the rendering of elements above that have previously been rendered.
+ *
+ * @param $element
+ *   The element to be hidden.
+ *
+ * @return
+ *   The element.
+ *
  * @see render()
  * @see show()
  */
@@ -5512,10 +5531,25 @@
 }
 
 /**
- * Show a hidden or already printed element from later rendering.
+ * Show a hidden element for later rendering.
+ *
+ * You can also use render($element), which shows the element while rendering
+ * it.
+ *
+ * If you are using this on an element low in the element tree, call show()
+ * before the first call to render() or drupal_render() on the containing
+ * element tree, or it will have no effect. The reason is that the first time
+ * you call drupal_render() on an element tree, drupal_render() marks each
+ * element in the tree with a #printed flag as it is rendered. Subsequent calls
+ * to drupal_render() will not traverse the tree below when a #printed flag is
+ * encountered. So if you use show() on a low-level element, it will have no
+ * effect on the rendering of elements above that have previously been rendered.
  *
- * Alternatively, render($element) could be used which automatically shows the
- * element while rendering it.
+ * @param $element
+ *   The element to be shown.
+ *
+ * @return
+ *   The element.
  *
  * @see render()
  * @see hide()