links.html.twig docs are out of date

Problem/Motivation

API page: https://api.drupal.org/api/drupal/core!modules!system!templates!links.ht...

1. The 'link' element is not documented.
2. The 'url' element is documented, but is not available in the template.
3. It is unclear for developers what the input is for the theme function.

Question for the Theme System / Twig maintainers

We have a case here where there is a preprocessing function that expects certain input from the render array, and then the Twig template expects the processed output of that as its input.

My question is whether in the Twig template we are supposed to document what comes in after preprocessing? In which case, where are we documenting what goes into the render array? This is kind of a generic question, not just for this issue:
- Module developers passing stuff from their module through a given theme hook -- where do they look for docs and what do they expect?
- Theme developers overriding a theme template -- where do they look for docs and what do they expect?