I just wrote some library code and I added a thread-safety clause to every class. Later, I found a typo and had to touch everything. Kotlindoc is awesome, especially when you are used to javadoc, but redundancy is something I which is still very annoying.
My idea is to add a @include block tag.
I have no good idea where to store the actual snipped text so that it can be referenced from comments later.
My first idea was, to do it via package annotations, but there is no AnnotationTarget.PACKAGE and no documentation can be added to an annotation when it’s used.
Alternatively, you could add a comment to a variable which can be referenced later. On the other hand it’s rather silly to have variables for documentation purposes, only.
Anyway, it would be awesome if I could add text to a package and reference it from every comment.
package org.example.stuff
/** This implementation is not thread-safe. */
val threadsafetyClause = kDocSnipped
/**
* Does something.
*
* @include threadsafetyClause
* @include org.example.licence.short
*/
class Stuff { ... }
Another cool side-effect is that it would be possible to create documentation snipped libraries, which contain snippets of well written text which could describe complex things in a short and easy to understand way. Other developer just could use these without being a poet and without bloating the code with comments.
What do you think?
