My apologies if this has been discussed before, but I couldn’t find it anywhere.
I was shocked yesterday to discover that scala.collection.mutable.Stack has a top method. I had looked for it multiple times before, thinking that it must be there. Eventually, I concluded that we were supposed to use head instead of top.
You may be saying, “Of course Stack has a top method!” And yes, it does. But try looking for it in the API. I’ll wait. … Ok, see the problem?
ScalaDoc sorts the methods alphabetically, so top should appear in between toMap and toSeq. But instead it appears 5 slots later, after toSeq, toSet, toString, and toVector.
Clearly, ScalaDoc is sorting, not alphabetically, but in ASCII order, where all uppercase letters come before all lowercase letters. Whereas my assumption was that it would be in dictionary order, which ignores case.
Was this ordering a deliberate choice? If not, would it hurt anything to switch to ignoring case going forward? It’s possible that it could be useful to treat an initial uppercase letter differently from an uppercase letter in the middle of a name.