diff --git a/core/includes/common.inc b/core/includes/common.inc
index 4389785..4be9406 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -5713,73 +5713,77 @@ function drupal_render_page($page) {
  *
  * Recursively iterates over each of the array elements, generating HTML code.
  *
- * 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, 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
- * markup around the rendered children; e.g., fieldsets add the required markup
- * for a fieldset around their rendered child elements. All wrapper theme
- * functions have to include the element's #children property in their output,
- * as it contains the output of the previous theme functions and the rendered
- * children.
- *
- * For example, for the form element type, by default only the #theme_wrappers
- * property is set, which adds the form markup around the rendered child
- * elements of the form. This allows you to set the #theme property on a
- * specific form to a custom theme function, giving you complete control over
- * the placement of the form's children while not at all having to deal with
- * the form markup itself.
- *
- * drupal_render() can optionally cache the rendered output of elements to
- * improve performance. To use drupal_render() caching, set the element's #cache
- * property to an associative array with one or several of the following keys:
- * - 'keys': An array of one or more keys that identify the element. If 'keys'
- *   is set, the cache ID is created automatically from these keys. See
- *   drupal_render_cid_create().
- * - 'granularity' (optional): Define the cache granularity using binary
- *   combinations of the cache granularity constants, e.g.
- *   DRUPAL_CACHE_PER_USER to cache for each user separately or
- *   DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to cache separately for each
- *   page and role. If not specified the element is cached globally for each
- *   theme and language.
- * - 'cid': Specify the cache ID directly. Either 'keys' or 'cid' is required.
- *   If 'cid' is set, 'keys' and 'granularity' are ignored. Use only if you
- *   have special requirements.
- * - 'expire': Set to one of the cache lifetime constants.
- * - 'bin': Specify a cache bin to cache the element in. Defaults to 'cache'.
- *
- * This function is usually called from within another function, like
- * drupal_get_form() or a theme function. Elements are sorted internally
- * using uasort(). Since this is expensive, when passing already sorted
- * elements to drupal_render(), for example from a database query, set
- * $elements['#sorted'] = TRUE to avoid sorting them a second time.
- *
- * drupal_render() flags each element with a '#printed' status to indicate that
- * the element has been rendered, which allows individual elements of a given
- * array to be rendered independently and prevents them from being rendered
- * more than once on subsequent calls to drupal_render() (e.g., as part of a
- * larger array). If the same array or array element is passed more than once
- * to drupal_render(), it simply returns a NULL value.
- *
  * @param $elements
- *   The structured array describing the data to be rendered.
+ *   The structured array ("renderable array" or "element") describing the data
+ *   to be rendered. 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 array
+ *   elements whose keys do not start with a '#'. Their values are themselves
+ *   renderable arrays, 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. The following properties
+ *   are common to all renderable arrays:
+ *   @render_property_all #type
+ *     The type of element to render, as defined in a hook_element_info()
+ *     implementation. Default property values for this element type from
+ *     hook_element_info() are added to the $elements array.
+ *   @render_proprety_all #pre_render
+ *     An array of functions to call, in order, before theming the element.
+ *   @render_property_all #theme
+ *     If set, the name of the theme hook to be used to render this element and
+ *     possibly its children (if any). If #theme is not set (or returns empty),
+ *     and the element has children, the default theming is to render each of
+ *     the children (by calling drupal_render() recursively) and concatenate.
+ *   @render_property_all #theme_wrappers
+ *     Array of theme hooks to be called, in order, after the #theme function
+ *     is finished, to add additional markup around the rendered element. This
+ *     allows the #theme property to be overridden, while still supplying
+ *     required markup.
+ *   @render_property_all #cache
+ *     To use caching to improve performance, set the #cache property to an
+ *     associative array with one or several of the following array elements:
+ *     - keys: An array of one or more keys that identify the element. If set,
+ *       the cache ID is created automatically from these keys. See
+ *       drupal_render_cid_create().
+ *     - granularity (optional): Define the cache granularity using bitwise OR
+ *       combinations of the cache granularity constants, e.g.
+ *       DRUPAL_CACHE_PER_USER to cache for each user separately or
+ *       DRUPAL_CACHE_PER_PAGE | DRUPAL_CACHE_PER_ROLE to cache separately for
+ *       each page and role. If not specified, the element is cached globally
+ *       for each theme and language.
+ *    - cid: Specify the cache ID directly. Either 'keys' or 'cid' is required.
+ *      If 'cid' is set, 'keys' and 'granularity' are ignored. Use only if you
+ *      have special requirements.
+ *    - expire: Set to one of the cache lifetime constants.
+ *    - bin: Specify a cache bin to cache the element in. Defaults to 'cache'.
+ *   @render_property_all #access
+ *     TRUE if the user has access to see this element; FALSE otherwise. If set
+ *     and FALSE, nothing is returned.
+ *   @render_property_all #weight
+ *     Numeric value indicating the order of children within a renderable array.
+ *     Children with lower values appear before those with higher values; can
+ *     be negative.
+ *   The following properties are used by one or more types of renderable
+ *   arrays, but not all types:
+ *   @render_property #markup
+ *      HTML markup for this element. If #type has not been set and #markup is
+ *      present, #type will be set to 'markup'.
+ *   @render_property #attributes
+ *      Attributes to add to the outer HTML tag of the element.
+ *   The following internal-use properties are common to all renderable arrays:
+ *   @render_property_internal #printed
+ *     During rendering, this function flags each element with a #printed
+ *     status to indicate that the element and its children have already been
+ *     rendered. If an already-rendered element is passed in, nothing is
+ *     returned from this function.
+ *   @render_property_internal #sorted
+ *     During rendering, children are sorted using uasort(), and the #sorted
+ *     property is set. Since this is expensive, when calling this function
+ *     with already-sorted elements, set #sorted to TRUE to avoid sorting a
+ *     second time.
+ *   @render_property_internal #children
+ *     The results of the theming are stored in this property during rendering.
+ *     See #theme and #theme_wrappers properties.
  *
  * @return
  *   The rendered HTML.
diff --git a/core/includes/form.inc b/core/includes/form.inc
index 85bffc6..fb6dfa1 100644
--- a/core/includes/form.inc
+++ b/core/includes/form.inc
@@ -285,8 +285,38 @@ function drupal_get_form($form_id) {
  *   behavior after form submission may be found in drupal_redirect_form().
  *
  * @return
- *   The rendered form. This function may also perform a redirect and hence may
- *   not return at all, depending upon the $form_state flags that were set.
+ *   The built and processed form array. This function may also perform a
+ *   redirect and hence may not return at all, depending upon the $form_state
+ *   flags that were set. Form arrays are like generic renderable arrays (see
+ *   drupal_render() for details), except that their #type property is 'form',
+ *   and their children are form elements. Besides the common renderable array
+ *   properties listed in drupal_render(), the following properties are common
+ *   to all form elements:
+ *   @form_property_all #disabled
+ *     If TRUE, the form element is disabled (greyed out).
+ *   @form_property_all #required
+ *     If TRUE, the form element is required to have a value to accept
+ *     submission.
+ *   @form_property_all #name
+ *     The HTML name of the form element.
+ *   @form_property_all #process
+ *     An array of functions called to process form submissions. See
+ *     form_builder() for details.
+ *   @form_property_all #value_callback
+ *     A function that maps user input to the element's #value property. See
+ *     form_builder() for details.
+ *   The following properties are used by some (but not all) form elements:
+ *   @form_property #description
+ *     The translated description of the form element, typically displayed
+ *     below the input field.
+ *   @form_property #title
+ *     The translated title of the form element.
+ *   @form_property #multiple
+ *     If TRUE, multiple selections are allowed for this form element.
+ *   @form_property #options
+ *     An array of options for this form element. The array elements are the
+ *     displayed option values, and the keys (if provided) are the returned
+ *     values for each option (if there are no keys, the array values are used).
  *
  * @see drupal_redirect_form()
  */
@@ -2557,15 +2587,20 @@ function form_process_select($element) {
 /**
  * Returns HTML for a select form element.
  *
+ * @form_element select
+ *
  * It is possible to group options together; to do this, change the format of
  * $options to an associative array in which the keys are group labels, and the
  * values are associative arrays in the normal $options format.
  *
  * @param $variables
  *   An associative array containing:
- *   - element: An associative array containing the properties of the element.
- *     Properties used: #title, #value, #options, #description, #extra,
- *     #multiple, #required, #name, #attributes, #size.
+ *   - element: A form element array containing the properties of the element.
+ *     @properties
+ *       #title, #value, #options, #description, #extra, #multiple, #attributes,
+ *       #options, #size.
+ *     @form_property_specific #size
+ *       The width of the select element.
  *
  * @ingroup themeable
  */
diff --git a/core/includes/theme.inc b/core/includes/theme.inc
index ad54638..74b58ea 100644
--- a/core/includes/theme.inc
+++ b/core/includes/theme.inc
@@ -2135,20 +2135,24 @@ function theme_feed_icon($variables) {
 /**
  * Returns HTML for a generic HTML tag with attributes.
  *
+ * @render_element html_tag
+ *
  * @param $variables
  *   An associative array containing:
- *   - element: An associative array describing the tag:
- *     - #tag: The tag name to output. Typical tags added to the HTML HEAD:
+ *   - element: A renderable array describing the tag.
+ *     @properties
+ *       #tag, #attributes, #value, #value_prefix, #value_suffix
+ *     @render_property_specific #tag
+ *       The tag name to output. Typical tags added to the HTML HEAD:
  *       - meta: To provide meta information, such as a page refresh.
  *       - link: To refer to stylesheets and other contextual information.
  *       - script: To load JavaScript.
- *     - #attributes: (optional) An array of HTML attributes to apply to the
- *       tag.
- *     - #value: (optional) A string containing tag content, such as inline CSS.
- *     - #value_prefix: (optional) A string to prepend to #value, e.g. a CDATA
- *       wrapper prefix.
- *     - #value_suffix: (optional) A string to append to #value, e.g. a CDATA
- *       wrapper suffix.
+ *     @render_property_specific #value
+ *       (optional) A string containing tag content, such as inline CSS.
+ *     @render_property_specific #value_prefix
+ *       (optional) A string to prepend to #value, e.g. a CDATA wrapper prefix.
+ *     @render_property_specific #value_suffix
+ *       (optional) A string to append to #value, e.g. a CDATA wrapper suffix.
  */
 function theme_html_tag($variables) {
   $element = $variables['element'];