3

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?

Kris Nuttycombe
  • 4,560
  • 1
  • 26
  • 29
  • 1
    The two classes to review are https://github.com/scala/scala/blob/2.12.x/src/compiler/scala/tools/nsc/ast/DocComments.scala and https://github.com/scala/scala/blob/2.12.x/src/scaladoc/scala/tools/nsc/doc/ScaladocAnalyzer.scala which if you search for usecase then you'll see that there does seem to be no way around the definition requiring a pass through the type checker. Sorry :( – Justin Pihony Aug 27 '17 at 17:51
  • @JustinPihony Thank you. In the usecase values in the stdlib, it seems like the usecase signature gets applied to some types concretely, and is thus simplified, do you think there might be any way of doing that here? – Kris Nuttycombe Aug 27 '17 at 21:44
  • Sorry for the delay, and sorry but I cannot find a way to make this work. Most of the stdlib docs I found just omitted aspects, such as implicits. The problem as far as I see it is that it cannot resolve the ? type...so maybe you could put a dummy type and try that - but that doesn't seem all that great. – Justin Pihony Nov 01 '17 at 03:46

0 Answers0