@MustBeDocumented for @Serializable #2056
Description
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) DurationHowever 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.