Documentation for link element

This issue is a discussion of the specifics of documenting the 'link element'. The issue of where this belongs is in #1190658: Where to document the link element (and future Render elements)?.

Here's what I have so far:

Description: Renders a link through #pre_render callback. Doing so during pre_render gives modules a chance to alter the link parts.

Properties: (see below)

Usage example (block.module):

      $page['page_top']['backlink'] = array(
        '#type' => 'link',
        '#title' => t('Exit block region demonstration'),
        '#href' => 'admin/structure/block' . (variable_get('theme_default', 'bartik') == $theme ? '' : '/list/' . $theme),
        // Add the "overlay-restore" class to indicate this link should restore
        // the context in which the region demonstration page was opened.
        '#options' => array('attributes' => array('class' => array('block-demo-backlink', 'overlay-restore'))),
        '#weight' => -10,
      );

Properties are more of a challenge. The main properties are documented in drupal_pre_render_link($element):
#title: The link text to pass as argument to l().
#href: The URL path component to pass as argument to l().
#options: (optional) An array of options to pass to l().

Also in that function:
#id
#attributes

Then there are the properties documented at the Render API doc: http://drupal.org/node/930760
#markup
#prefix/#suffix
#pre_render (not sure this applies here, since the element is by definition processed in pre-render)
#post_render
#theme
#theme_wrappers
#cache

In the usage example above, there's also:
#weight
So there may be other FAPI properties available.