Daniel Murphy:
I agree, the signatures are basically unreadable.
In Scala they have added the @usecase annotation to face this
problem:
https://wiki.scala-lang.org/display/SW/Tags+and+Annotations
From that page:
@usecase <simple definition> In case the method definition is too
complex, you can add simple aliasing definition as a usecase. It
will create another entry in the scaladoc page as if the <simple
definition> actually existed. The description for the newly
created entry is the same as the one for the current symbol, just
that it's preceded by [use case] to signal it's not a real entry.
An example can be seen in the ++ method of
scala.collections.immutable.Set.
Elsewhere there is written:
the usecases inherit the comments from their parents, such
as the explanation and the annotations: @param, @tparam, @return,
etc.
Bye,
bearophile
