Scaladoc feature to show definition source inline

Tooling
1

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?

8 Likes
2

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

3

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.

5 Likes
4

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
5

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)

Cheers,

Corey

3 Likes
6

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…

3 Likes
7

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.

2 Likes