2.13: Collection hierarchy diagrams in collections guides are out of date

[SethTisue]

They were updated at some point in the 2.13 cycle, but they aren't exactly right for 2.13.0, for example we noticed that TreeSeqMap and CollisionProofHashMap were missing.

[Philippus]

I think @mslinn is working on this? https://github.com/mslinn/scala-collections-charts/tree/2.13

[mslinn]

The reworked collection charts are ready for review at https://github.com/mslinn/scala-collections-charts/tree/2.13

[NthPortal]

should they include IterableOnce?

[mslinn]

I don't think that end users should care about an implementation detail

[NthPortal]

IterableOnce is a trait (implemented by Option, no less, though I'm not sure I'd put that in the diagram)

[mslinn]

The goal of this project is merely to provide end users an intuitive understanding of the collection classes. Conceptually IterableOnce is a distinction without a difference to everyone except to library authors of collection classes. I will add a description of the goals and non-goals of this project to the README.

[dwijnand]

Isn't whether a collection can be iterated only once or multiple times an important distinction?

[mslinn]

These charts are not intended to replace the need for written documentation. If it would be possible to include that level of detail in the charts, and keep them easy to read, that would be fine. If this is the only (deliberate) omission, then lets include it. Before making that decision, lets consider what else might be included with that level of detail.

Alternatively, it might be possible to use UML annotation instead to show 0..1 iterations, but again that would required fine print and I would argue against an accurate but confusing and mostly illegible set of charts.

I also did not include any deprecated classes or interfaces, and some obscure concrete classes. My touchstone was along the lines of the Pareto Principle: delivering 80% of the value by only considering 20% of the detail. Many more people will be helped if most readers can easily understand a simpler but deliberately incomplete set of charts. Scala is very large and quite complex. Most programmers are unwilling to endure the pain necessary to grok it sufficiently well in order to work with it effectively. Completeness is the enemy of understanding, rather like perfect is the enemy of the good (enough).