Conflicting documentation advice on depset#to_list() in binary rule

Bazel docs are at odds with themselves on recommended depset usage.

> To actually get the performance advantage, it’s important to not retrieve the contents of the depset unnecessarily in library rules. One call to to_list() at the end in a binary rule is fine, since the overall cost is just O(n). It’s when many non-terminal targets try to call to_list() that we start to get into quadratic behavior.
>
> https://docs.bazel.build/versions/master/skylark/depsets.html#performance

> A common misconception is that you can freely flatten depsets if you only do it at top-level targets, such as an _binary rule, since then the cost is not accumulated over each level of the build graph. But this is still O(N^2) when you build a set of targets with overlapping dependencies. This happens when building your tests //foo/tests/..., or when importing an IDE project.
>
> https://docs.bazel.build/versions/master/skylark/performance.html#avoid-calling-depsetto_list

Read the linked depsets performance section and the performance page’s “avoid calling depset.to_list” section first. Compare their guidance about flattening depsets in binary or top-level targets, then update the Bazel documentation so the recommendation is consistent and both examples accurately describe the performance tradeoff.

Written by the indexing model from the issue text.