Where to document the link element (and future Render elements)?

The 'link element' causes a lot of confusion. As far as I can tell, it's not really documented anywhere. Many people assume it is an element of the Form API and should be documented in the FAPI reference.

The 'link element' is part of the Render API and can be used outside forms as well as inside. So it is fundamentally different from the elements documented in the FAPI reference. But it functions a lot like those and takes many of the same properties.

The two most obvious places to document the 'link element' are:
FAPI reference: http://api.drupal.org/api/drupal/developer--topics--forms_api_reference....
Render API doc: http://drupal.org/node/930760

A good case can be made for either. The Render API doc lists many of the render element properties, and 'link' is part of the Render API. It already mentions this element in passing already.

The 'link element' is often used in forms, and many render element properties are already documented in the FAPI reference. It's also the place many if not most people go to find documentation for it. Putting it here gives the opportunity to explain the difference to those people and refer them to the Render API for further information. Whichever place 'link' finally ends up should include a reference to the other.

At the end of Franz Heinzmann's session on the Render API in Drupal 7 at Drupalcon Chicago, he projected a shared library of reusable interface elements. I'm thinking 'link' is the first of these. If that's true, then this is a larger question than just where to document the 'link element.'

I lean toward putting it in the FAPI reference. Even if render elements are different, they will be often used in forms. I would create a separate area for them, a list under the second table (Special Elements) called Render Elements. With only one element, a full table seems overkill, but could be added later as more elements are created. The full description of the 'link element' would be added to the main element list, linked to the item in the Render Element list (like the form element headers in the table). This list would probably only grow in the D8 version, of course. (I'd be surprised if more render elements are created in D7, but I could be wrong.)

If/when the plans in #100680: [meta] Make API module generate Form API documentation come to fruition, whatever format is developed could take on Render elements as well. But for now, we need a place to put this.

I also need some input on the exact documentation for the 'link element' and its properties. But this is already getting long, so I'll open a second issue for that.