scaladoc sorts in ASCII order

[martijnhoekstra]

reproduction steps

https://www.scala-lang.org/api/current/scala/collection/mutable/Stack.html sorts top after toVector as reported on https://contributors.scala-lang.org/t/scaladoc-ordering/4503

problem

This is sorted in ASCII order rather than alphabetical. I suspect a quick fix is possible at in https://github.com/scala/scala/blob/26dd17aebc988ba84c243e6f23796680df0d4a26/src/scaladoc/scala/tools/nsc/doc/model/Entity.scala#L79 with a toLowerCase

[nafg]

Can someone explain to me why case-insensitive sort is better? Strings are almost always sorted this way.

[SethTisue]

fwiw I tried javadoc on:

package foo;

public interface J {
  void toList();
  void toVector();
  void top();
}

and the output has the case-insensitive sort order:

Modifier and Type	Method and Description
void	toList()
void	top()
void	toVector()

[martijnhoekstra]

I replied with the "I'm confused now" confused smiley, not the "I don't think this is a good idea but I'm not about to write that out in words" confused smiley. It can be difficult to spot the difference.

[NthPortal]

personally, I like toList and toVector being grouped, as they're semantically closer? and my intuition says that that holds for methods in general, but I can't actually prove that

[dwijnand]

I think it's good practice to make human-facing text alphabetical rather than, what I've found out is called, "ASCIIbetical" order. But when the human is a developer and the case is significant, then ASCIIbetical might be the better choice.

[martijnhoekstra]

If toList and toVector should be grouped, shouldn't we just use a @group for it?

[NthPortal]

I just mean that semantically, toList and toVector are closer than either is to top

[eed3si9n]

sortWith
sorted

might be an interesting case to ponder.

Also supposed we have:

sortForList
sortForVector
sortForall
sortForeach
sortWith
sorted

ASCII ordering + camel casing creates an interesting effect as if the methods are sorted by camel-cased words, but it could require multiple scanning of A-Z, a-z trying to look for sortForeach if you can't remember the exact casing (after all you're in the Scaladoc).

Case insensitive sorting would do:

sorted
sortForall
sortForeach
sortForList
sortForVector
sortWith

[NthPortal]

but it could require multiple scanning of A-Z, a-z trying to look for [...] if you can't remember the exact casing

that's a very good point, and I think a more compelling one

[nafg]

Maybe instead of sorting by the name as a single word, it should sort by words, case-insensitive. Something like: def symbolToWords(sym: String): Seq[String] = ... symbols.sortBy(symbolToWords)(Ordering.Iterable(Ordering.comparatorToOrdering(String.CASE_INSENSITIVE_ORDER)))

…

On Tue, Sep 15, 2020 at 4:53 PM Princess | April ***@***.***> wrote: but it could require multiple scanning of A-Z, a-z trying to look for [...] if you can't remember the exact casing that's a very good point, and I think a more compelling one — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#12149 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAYAUDFPYIW5QUPEOXT2TTSF7H3DANCNFSM4RFHKUMA> .

[dwijnand]

but it could require multiple scanning of A-Z, a-z trying to look for [...] if you can't remember the exact casing

that's a very good point, and I think a more compelling one

I agree it makes a compelling argument but

multiple scanning of A-Z, a-z trying to look for sortForeach if you can't remember the exact casing

implies (to me) a lack of naming convention or at least a lack in consistency. When a convention is applied consistently, as in the top/toList/toVector case, the ascii order presents better results.

So I think I still favour ASCIIbetical ordering, as if you're looking specifically for "sortforeach" the search functionality should be case-insensitive and find you sortForeach.