@MustBeDocumented for @Serializable

[lukellmann]

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

#2048 promotes typealiases for use with @Serializable.

We already use it in our library and it works as expected:

/** A [Duration] that is [serializable][Serializable] with [DurationInSecondsSerializer]. */
public typealias DurationInSeconds = @Serializable(with = DurationInSecondsSerializer::class) Duration

However when using Dokka, the output looks like this:

This might be confusing for users of our library as it doesn't seem to make any sense to use this typealias. The important information that a custom serializer is added with this annotation is missing.

Describe the solution you'd like

To support this, annotation class Serializable would simply have to be annotated with the MustBeDocumented meta-annotation:

@MustBeDocumented
@Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS, AnnotationTarget.TYPE)
public annotation class Serializable(val with: KClass<out KSerializer<*>> = KSerializer::class)

The Dokka output then looks like we would like to:

Other effects of this solution that should be considered

@Serializable can be used in other places too:

• on classes -> I would argue that it is also desirable that Dokka output shows the information that some class is serializable.

  @Serializable // would be documented
  data class User(val name: String)

• on properties -> I'm not sure if it is desirable that Dokka output shows the information which exact serializers are used.

  @Serializable
  data class User(
      @Serializable(with = MyCustomStringSerializer::class) // would be documented
      val name: String
  )

• on types -> Same as for properties, I'm not sure if it should be shown.

  @Serializable
  data class User(    // would be documented
      val names: List<@Serializable(with = MyCustomStringSerializer::class) String>
  )

Other annotations that might be worth documenting

Maybe @MustBeDocumented could also be added to some other annotations, I'm thinking of @SerialName, @Required and @Transient.

[qwwdfsad]

Thanks for the detailed write up!

[sandwwraith]

I'll close this for now because it is fixed in #2059.
However, you may create a new issue for @SerialName/@JsonClassDiscriminator if you have reasons for them to be documented too

[lukellmann]

@SerialName, @Required, @Transient and @EncodeDefault are now also annotated with @MustBeDocumented. Issue: #2386, PR: #2407