How do I get scaladoc's @usecase annotation to just print the string I give it?

169 views Asked by At

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?

0

There are 0 answers