I'm writing some documentation for my exception classes and am running into the following warning from scaladoc:
The comment for class BarException contains @inheritdoc, but no parent comment is available to inherit from.
After reading this Java question I have to imagine that the reason for this is because I want to inherit documentation on the constructor method and not just a normal method:
/** Base Exception
*
* @param msg A message describing this exception
* @param cause The exception which is the underlying cause to this FooException, null if this is the underlying cause
*/
abstract class FooException(val msg: String, val cause: Throwable) extends RuntimeException(msg, cause)
/** The bar exception specific docs, expect msg & cause to be given same docs as FooException
* @inheritdoc
*/
case class BarException(override val msg: String, override val cause: Throwable) extends FooException(msg, cause)
I understand that there's no override of the constructor, and so nothing to inherit from for that. But, That said, if I look at the generated documentation for the parent FooException I see that not only does the constructor have the arguments documented as expected, but also the fields of msg and cause are documented too. Which seems to imply to me that scaladoc has taken the @param and applied it to my fields for FooException in addition to using it as the method param documentation
Since I have to override in the case class constructor of BarException, I'd expect scaladoc to understand that there is something being overridden and therefore something to inherit documentation from, but this isn't the case. I've looked through the scala tags wiki but haven't found anything about this behavior or how to get the documentation to inherit from the properties in the parent class to the children.
If I change the class to use def then I can inherit documentation onto the fields of the children, but I have to repeat myself:
/** Base Exception
*
* @param msg A message describing this exception
* @param cause The exception which is the underlying cause to this FooException, null if this is the underlying cause
*/
abstract class FooException(msg: String, cause: Throwable) extends RuntimeException(msg, cause) {
/** A message describing this exceptionxx */
def msg: String
/** The exception which is the underlying cause to this FooException, null if this is the underlying cause */
def cause: Throwable
}
Is there anyway to not use the def format in the abstract class and just inherit the documentation to the child that scaladoc is already producing for the generated properties of the parent class?
