KtDoc / Dokka - @inheritDoc

Language Design
1

I am new to Kotlin and exploring among other things the KtDoc / Dokka generated documentation.

I see that there is no equivalent to the JavaDoc @inheritDoc in Kotlin (ie. for inherited methods).

On a forum somewhere I saw a comment (don’t know if it was from a contributor or not) that the inheritDoc statement on many methods is superfluous and adds unnecessary lines - and if an inherited method doesn’t provide its own documentation, the documentation comes from the parent method.

While I sort of get that what I really don’t like is the mish-mash of documented and undocumented code.

I am always harping on my colleagues to document their code and the @inheritDoc indicates at least that there is some documentation available and that the code author has at least put some thought into it.

Any chance of getting an equivalent in Kotlin?

1 Like
2

I do not see @inheritDoc as any indication that the author has put any thought into the documentation; it’s too easy to add mechanically. At this time we have no plans to support @inheritDoc.

3

sorry, I have now commented on a similar issue on an existing dokka issues which I guess is the better location:

Probably best to continue the discussion there.

However, what you can do with inherit doc is extend the original documentation without doing a complete copy/paste:

 /**
  * {@inheritDoc}
  * This particular implementation does a extra foo with bar.
  */
3 Likes
4

I am interested in knowing the reason for not supporting @inheritDoc.
I find it extremely useful when a concrete implementation needs to add further info to the interface / superclass documentation. Can’t really see how this is achievable without copying and pasting the same comments over and over, or forcing the user of a class to make an additional click in the IDE to see the full docs on an overridden function.

2 Likes