I'm attempting to use the @usecase scaladoc annotation to simplify a complicated type which has been uglified in the process of kind-projector constructing a type lambda for me. Here is the function in question:
def oneOf[P[_], I](alts: List[Alt[Schema[Unit, P, ?], I, B] forSome {type B}]): Schema[Unit, P, I]
By the time it gets to scaladoc, however, it's gotten pretty mangled:
def oneOf[P[_], I](alts: List[Alt[[γ$13$]HCofree[[β$0$[_$1], γ$1$]SchemaF[P, β$0$, γ$1$], Unit, γ$13$], I, _]]): Schema[Unit, P, I]
I'd love it if I could just have the original function definition in the scaladocs, so I attempted to use the @usecase annotation to give it my own definition:
/** Builds an un-annotated schema for the sum type `I` from a list of alternatives.
*
* Each alternative value in the list describes a single constructor of `I`.
* For example, to construct the schema for [[scala.util.Either]] one would provide
* two alternatives, one for the `Left` constructor and one for `Right`.
*
* @usecase def oneOf[P[_], I](alts: List[Alt[Schema[Unit, P, ?], I, _]]): Schema[Unit, P, I]
*/
def oneOf[P[_], I](alts: List[Alt[Schema[Unit, P, ?], I, B] forSome {type B}]): Schema[Unit, P, I] =
However, it looks like the @usecase value is actually being processed somehow by the Scala compiler, and nothing I do can convince it to allow me to use this string directly. Here's a sample error:
> doc
[info] Main Scala API documentation to /home/nuttycom/schematic/target/scala-2.12/api...
[error] /home/nuttycom/schematic/src/main/scala/schematic/Schema.scala:106: not found: type ?
[error] * @usecase def oneOf[P[_], I](alts: List[Alt[Schema[Unit, P, ?], I, _]]): Schema[Unit, P, I]
[error] ^
[info] No documentation generated with unsuccessful compiler run
Is there any mechanism that I can use to get scaladoc to not attempt to parse or otherwise validate the usecase string?