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

[pauldraper]

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

[brandjon]

Right, the first paragraph can be tweaked to mention that one call at the end of a binary rule avoids quadratic behavior if there are no other such binary rules in the same build. The intent was to contrast with flattening at every level of a chain of library targets.

[pauldraper]

I agree the first recommendation seems more appropriate than the second.