Documentation incorrectly recommends hook_link_alter to add links

hook_link_alter is called twice per node; Once for the links section (links like 'read more', normally below the node body), and once for the taxonomy links section (links to terms, normally above the node body). If hook_link_alter is used to add a link, this link to the $links array, this link shows up on both sections. This leads to confusion: http://drupal.org/node/217017. Instead, it is more logical to use hook_link to add a link to the links section.

The api documentation describes hook_link_alter as follows:
Perform alterations before links on a node are rendered. One popular use of this hook is to add/delete links from other modules.
This would be a better description:
Perform alterations before links on a node are rendered. One popular use of this hook is to modify/remove links from other modules.
The description would probably benefit from the following addition:
If you want to add a link to the links section of a node, use hook_link instead.