Scaladoc feature to show definition source inline

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. :slight_smile: 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.

Worth pursuing?


Yes I’ve thought this myself. Sometimes the implementation is the perfect documentation.

I think that the ability to go to the source definition would be useful regardless of the length of the implementation. Therefore, I’d suggest to show a link to the source definition (on the project’s source repository), instead of inlining the definition in the documentation.


While I think that would also be useful, the extra level of indirection is a bit much for something that’s almost a trivial definition (like def nonFoo: boolean = !isFoo)

1 Like

That would be similar to haddock. Some libraries already link to the site per class, bit not per definition. While a nice optional feature to have in addition, it’s not a suitable alternative:

  1. The source may not be publicly available. (Eg: commercial, closed source). No reasonable place to link to.

  2. Less efficient user experience to always requiring clicking a link. From my experience using haddock documentation: for such definitions, going to the source was such a common operation that inlining that operation would save a significant amount of time. (Puns intended)




So long as it’s optional and upward-compatible (as this new @source operation would be), this seems like a win. When the code is self-documenting enough, I can choose to embed it with very little ceremony, and folks can see that with a minimum of fuss.

I like it…


Thanks for the feedback everybody!

I’m still interested in implementing this. One of many scaladoc features I think would improve usability :slight_smile: Unfortunately, I won’t have a chance to look into this for a few months.

A concrete example where this would be useful:

to support customers debugging an exit the value should be included in the docs. This feature would save me the effort of keeping this up to date.