KDoc: reuse text snippets and comment libraries


#1

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?


#2

Yes, I think that’s a pretty cool idea. Dokka already allows including parts of source code in the doc comment through the @sample tag, so it’s just natural to also support including pieces of documentation.

As for where to store the snippets, I would follow the existing solution for module documentation and store them in a separate .md file. For example, this file is right now parsed to extract the descriptions for packages in the stdlib. We could use a similar structure (heading is the name of the snippet, everything following the heading is its text) to store incudeable snippets.

Want to contribute the implementation? :slight_smile:


#3

Yeah, I’m just cloning dokka. Is there a good point to start at, ie some documents or guidelines?