@SerialComment annotation

[slava110]

What is your use-case and why do you need this feature?

@SerialComment annotation will be useful for automatically generated configuration files. Some serialization libraries already implemented that feature including:

• akuleshov7/ktoml
• charleskorn/kaml
• Him188/yamlkt

And it's possible to add comment support in other libraries like:

• kotlinx.serialization.properties
• kotlinx.serialization.hocon
• adamko-dev/json5-kotlin

The problem is that they are using/will use different @Comment annotations

Describe the solution you'd like

• Add @SerialComment annotation
• SerialDescriptor.getElementComment(index: Int): String function to get property comment
  SerialFormat.supportsComments property to check if SerialFormat supports comment serialization (false by default)

[pdvrieze]

In other words, is it correct to summarise that you see a use case for having generalized support for including comments into serialized documents. Before we go thinking through what it really means there is one point about the supportsComments property. It is not clear why this would be useful as the comment is defined on types (serialdescriptor - and always format independent) not values and I don't see how any code would validly use this property.

Another part is what shape would these comments take. It appears that you want to have the annotation be specified on types, not use sites/fields. However the question is how a format would interpret this. If it is a top level comment, would this be included as part of the "document" comments? If not, will this be written out any time the type is written? (only the first time instead)? These choices need to be clear for a general purpose library. Perhaps making it easier to extend the format for this purpose may make things easier.

Besides these questions I'm not sure what the exact use case is. Is it only to have a top level comment on a document? In such case that is something best directly done directly on the format (perhaps when configuring it) although some sort of common configuration could be beneficial.

[slava110]

Yep, maybe there's no point in supportsComments, let's forget about it

It appears that you want to have the annotation be specified on types, not use sites/fields

Actually I wanted to have the annotation be specified on properties, not types, yeah (Updated my original comment)
I think comments should be written on each serialization (is it even possible to restrict it to first time only from kotlinx.serialization?..)

Besides these questions I'm not sure what the exact use case is

Commented properties are useful for any type of automatically generated configuration files. Developers will be able to tell users what should be put in certain JSON properties for example

[pdvrieze]

@slava110 So the use case is really configuration files. I can see that one. It doesn't really suffer from the repetition issue much and I certainly recognize the value of explanations/instructions in configuration files.
As to first time only, the format would need to maintain a set with type/field information that has already been written.

[whyoleg]

BTW, even if protobuf doesn't support comments in messages, it could be useful for schema generation to have comments there.
Another thing, that should be considered, is that when we will have something like SerialComment, then it will be a little confusing, when we will have both description for property and similar/different text in SerialComment. Not an issue, but something we should keep in mind.
Ex.

/**
 * @property used for ...
 */
data class SomeData(
  @SerialComment("property used for ...")
  val property: String
)

[slava110]

@pdvrieze I think maintaining set of type/field information that has already written will add unnecessary complexity and will create more questions. It's an idea for completely different issue
Currently kotlinx.serialization formats are writing everything each time object serialized (at least most of them, maybe some aren't) so comments should be written on each serialization too

[vnermolaev]

@slava110, I guess you can already achieve the goal as follows

@SerialInfo
@Target(AnnotationTarget.PROPERTY)
annotation class SerialComment(val comment: String)

fun SerialDescriptor.getElementComment(index: Int): String =
  getElementAnnotations(index)
      .filterIsInstance<SerialComment>()
      .singleOrNull()
      ?.comment
      ?: ""

@Serializable
data class Container(
    @SerialComment("Property is used for demonstration")
    val i: Int
)

fun main(args: Array<String>) {
    println(Container.serializer().descriptor.getElementComment(0))
}

[slava110]

@slava110, I guess you can already achieve the goal as follows

@vnermolaev , Please read my first comment in this issue. Thanks

[sgammon]

@whyoleg > BTW, even if protobuf doesn't support comments in messages

do you mean at runtime? protobuf does support comments in messages. actually this is my use case for finding this issue.

@pdvrieze perhaps my use case helps too. i want to preserve comments from Kotlin data class properties so that i can express them in generated .proto files. the proto files are used downstream and the comments are meaningful there -- they turn into code hints and other useful things that we want to keep in sync with the property comments on the source of truth (the kotlin data class).

i will try your workaround @vnermolaev because i'm extending the protobuf generator, so this may work for me.

[sgammon]

i wonder, though, if it is possible to do make this happen without a dedicated annotation. does the compiler plugin support comments? could it just take the native Kotlin comment from the property?

[solonovamax]

Is this issue being worked on at all?

I'd really love to see comment support in kotlinx.serialization

[sandwwraith]

@solonovamax No, it is not in our current plans.