An idea for scaladoc I’ve been wondering about that I’d like to get the community’s thoughts on:
I find that useful documentation for short, algebraic equations is exactly the equation itself. For example consider the following:
// from zio final def isEmpty: Boolean = length == 0 // from glngn final val encoder: ResourceRep.Encoder[T] = encode(_) // from cats def coflatten[A](fa: F[A]): F[F[A]] = coflatMap(fa)(fa => fa)
I would like to have the option to see those definitions inline in the documentation.
Personally, I’d be happy to see definitions inline for all definitions with a “small enough” metric. That’s likely too aggressive. A scaladoc annotation would likely be appropriate. Consider:
/** * `coflatten` is the dual of `flatten` on `FlatMap`. Whereas flatten removes * a layer of `F`, coflatten adds a layer of `F` * @source * ... */
would result in the (pretty printed) source for
coflatten being copied to that location in the docs.