Single ScalaDoc comment for overloads

Would it make more sense to have a single ScalaDoc comment for method overloads? It seems to that as the user of a method name, you want to know what your range of parameter options are and for the user, particularly the beginner, whether those options comes from name overloads, or from default values is really irrelevant.

I’ve taken to using identical comments on each overload method.

4 Likes

Usually when I overload, there’s enough differences in the way the parameters are used to justify separate explanation of the parameters, some justification for why it exists, and possibly an example.

That being said, at the top of all of that there’s usually a “what this does” section that’s pretty much identical for all the overloads, so a way to mark that out would be really helpful.

e.g. something like this:

/**
 * <<<
 * This does stuff
 * This is why it does stuff
 * 
 * Important warning about how it does stuff
 * >>>
 * 
 * Something specific to the `a`/`b` overload
 *
 * {{{
 *   assert(foo(a, b) == ???)
 * }}}
 *
 * @param a this param is an [[A]] that must ...
 * @param b this param is a [[B]] that can't ...
 * @returns a [[C]] with ...
 */
def foo(a: A, b: B): C = ???

/**
 * @overloads foo(A,B)
 * 
 * Something specific to the `d` overload
 * 
 * {{{
 *   assert(foo(a, b) == foo(da(d), db(b))
 * }}}
 *
 * @param d this param is a [[D]] that must ...
 */
def foo(d: D): C = ???

Could be equivalent to something like this:

/**
 * This does stuff
 * This is why it does stuff
 * 
 * Important warning about how it does stuff
 * 
 * Something specific to the `a`/`b` overload
 *
 * {{{
 *   assert(foo(a, b) == ???)
 * }}}
 *
 * @param a this param is an [[A]] that must ...
 * @param b this param is a [[B]] that can't ...
 * @returns a [[C]] with ...
 */
def foo(a: A, b: B): C = ???

/**
 * This does stuff
 * This is why it does stuff
 * 
 * Important warning about how it does stuff
 * 
 * Something specific to the `d` overload
 * 
 * {{{
 *   assert(foo(a, b) == foo(da(d), db(b))
 * }}}
 *
 * @param d this param is a [[D]] that must ...
 * @returns a [[C]] with ...
 */
def foo(d: D): C = ???
2 Likes

You mean some sort of “@include” such that you don’t need to keep sync between a comment and that of other overloads/overrides? Sounds useful, especially if tooling can follow it automatically and put the final doc together on its own.