Deprecate the @usecase scaladoc tag ? #584
Description
@usecase was introduced to make some signatures less scary, but it can be confusing and sometimes downright misleading (e.g. https://www.scala-lang.org/api/2.12.7/scala/collection/Map.html#map[B](f:A=%3EB):scala.collection.Map[B]).
With the collection redesign in 2.13, @usecase is almost not used anymore, the remaining usage is giving "simpler" signatures that violate variance checks (and this isn't done consistently, e.g. List#:: gets a usecase but List#::: doesn't):
% rg @usecase src/library
src/library/scala/collection/IterableOnce.scala
766: * @usecase def copyToArray(xs: Array[A]): Int
784: * @usecase def copyToArray(xs: Array[A], start: Int): Int
815: * @usecase def copyToArray(xs: Array[A], start: Int, len: Int): Int
837: * @usecase def sum: A
855: * @usecase def product: A
871: * @usecase def min: A
890: * @usecase def minOption: Option[A]
908: * @usecase def max: A
927: * @usecase def maxOption: Option[A]
947: * @usecase def maxBy[B](f: A => B): A
980: * @usecase def maxByOption[B](f: A => B): Option[A]
1001: * @usecase def minBy[B](f: A => B): A
1035: * @usecase def minByOption[B](f: A => B): Option[A]
src/library/scala/collection/Map.scala
126: * @usecase def getOrElse(key: K, default: => V): V
src/library/scala/collection/immutable/List.scala
98: * @usecase def ::(elem: A): List[A]
426: * @usecase def mapConserve(f: A => A): List[A]
src/library/scala/collection/immutable/Map.scala
102: * @usecase def updated(key: K, value: V): Map[K, V](Github search doesn't like "@" apparently so I can't say how much this is used in the wild, but I would guess very rarely)
Given the implementation complexity of usecase (it ties documentation generation to typechecking), it may be time to rethink whether this is a feature we should support at all. What do people think ? /cc @odersky @Duhemm