An issue that complicates generating suitable scaladoc comments for the collections library (as witnessed in #6947) is the current inheritance scheme for scaladoc comments. Take this example:

trait A { /** A */ def f: Any }
trait B extends A { def f: Any = ??? }
trait C extends A { /** C */ def f: Any }
trait D extends B with C
trait D2 extends B with C { /** D */ def f: Any }

As (correctly) listed by scaladoc, the linear supertypes of D and D2 are: C, B, A, AnyRef, Any.

Quiz: What do the comments for D.f and D2.f show?

Perhaps surprisingly, they both show "A" with definition classes B -> A. The reason is that scaladoc prefers concrete method definitions over abstract ones, such that both comments are taken from B.f which inherits the comment from A.f. This makes it impossible to refine comments independent of implementations in an inheritance pattern with intertwined definition and implementation traits, as used by the collections library. The only way to get a new comment for D.f is through a concrete definition:

trait D3 extends B with C { /** D */ def f: Any = super.f }

This situation could be improved by always following the linearization order for the enclosing template. In the example, C comes before B and A in the linearization of D, therefore D.f inherits the comment from C.f.

An alternative proposal by @adriaanm is to keep the current scheme of preferring cocrete definitions over abstract definitions but treat definitions with a new doc comment as concrete for this purpose.