Improve documentation for EntityType::$links

Updated: Comment #0

Problem/Motivation

The documentation for EntityType::$links reads as follows:

Link templates using the URI template syntax.

Links are an array of standard link relations to the URI template that should be used for them. Where possible, link relationships should use established IANA relationships rather than custom relationships.

Um... come again? I have no idea what "Links are an array of standard link relations to the URI template that should be used for them" means. I also shouldn't have to google "IANA relationships."

The change notice is slightly less opaque:
https://drupal.org/node/2020491

Proposed resolution

Let's please rewrite this whole docblock so that it's comprehensible to mere mortals.

1. First of all, the first line should be a lot more about "what the heck is this for" with less implementation detail. Maybe something like:
   

   Link patterns for the entity.

2. Then, we can go on to explain that they use the "URI template syntax" (and define WTF that is or link a definition; I'm assuming it means the curlies and crap for arguments in the router?)
3. IANA should also have some @link action to the same reference the change notice uses.
4. The current second paragraph needs a serious rewrite to make sense.
5. An example near the top of the docblock (perhaps with node/{node}, node/{node}/edit, etc.) would go a long way to illustrating the important point: This is the only way Drupal knows where the heck your entities are and how to perform operations on them.

Remaining tasks

Postponed on 📌 Convert entity type discovery to PHP attributes Needs review

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet