Format multiple annotations and `@[annotation1 annotation2]` notations

[Jolanrensen]

Expected Rule behavior

Some libraries have a lot of annotations. This is more common in server-side libraries that use Spring, for instance. However, this can become quite cluttered when unformatted or unstructured.

Take a look at the following example from the wild:

@[Deprecated(DEPRECATED_ACCESS_API) AccessApiOverload]
@Suppress("INAPPLICABLE_JVM_NAME")
@JvmName("frameColDataFrameKProperty")
public fun <C> AnyColumnGroupAccessor.frameCol(property: KProperty<DataFrame<C>>) = TODO()

I wonder, is KtLint familiar with the @[annotation1 annotation2] notation?

What I would recommend the rules to do:

• enforce lexicographical order of annotations, similar to imports, putting @[] annotations at the bottom (as they're often the longest):

@JvmName("frameColDataFrameKProperty")
@Suppress("INAPPLICABLE_JVM_NAME")
@[AccessApiOverload Deprecated(DEPRECATED_ACCESS_API)]
public fun <C> AnyColumnGroupAccessor.frameCol(property: KProperty<DataFrame<C>>) = TODO()

• if a @[] spans multiple lines, they should be indented together, with a single annotation per line (this is currently not recommended):

@[
JvmName("frameColDataFrameKProperty") Suppress("INAPPLICABLE_JVM_NAME")
AccessApiOverload
Deprecated(DEPRECATED_ACCESS_API)
]
public fun <C> AnyColumnGroupAccessor.frameCol(property: KProperty<DataFrame<C>>) = TODO()

should become something like this:

@[
    AccessApiOverload
    Deprecated(DEPRECATED_ACCESS_API)
    JvmName("frameColDataFrameKProperty")
    Suppress("INAPPLICABLE_JVM_NAME")
]
public fun <C> AnyColumnGroupAccessor.frameCol(property: KProperty<DataFrame<C>>) = TODO()

• Using @[annotation] should be replaced by @annotation
• Using @[annotation1 annotation2] on one line is fine if they fit. Else they should spread across multiple lines.
• Using 3+ annotations (or a customizable other number) without @[] will be replaced with the @[annotation1 annotation2 annotation3] syntax
• Using multiple @[] is allowed to group annotations together, but they should be ordered by width

@[AccessApiOverload Deprecated(DEPRECATED_ACCESS_API)]
@[JvmName("frameColDataFrameKProperty") Suppress("INAPPLICABLE_JVM_NAME")]
public fun <C> AnyColumnGroupAccessor.frameCol...

Some other ideas for improvements are welcome, of course :)
Unfortunately, there are not any guides regarding this Kotlin feature yet.

[paul-dingemans]

Thnx for proposing. There is some overlap with #2172, but there was a lack of a common opinion about what the preferred style would be. It would be great if you can merge the #2171 insights into this issue. Maybe, we should just create a new experimental rule to get the discussion started.

[Jolanrensen]

@paul-dingemans thanks!

Personally, I didn't even know this notation was possible:

@A @field:[C B]
val string: String

@set:[A B] @get:[C D]
val string: String

@get:[A B] @get:[C]
val string: String

With my proposed rules, it would look like this:

// `@[]` are put at the bottom, sorted by width, inside ordered lexicographically
@A
@field:[B C]
val string: String

@get:[C D]
@set:[A B]
val string: String

// `@[a]` becomes `@a`
// `@[]` are put at the bottom, sorted by width, inside ordered lexicographically
// arbitrary grouping is allowed, no need to put all annotations in one `@[]`
@get:C
@get:[A B]
val string: String

The reason I wouldn't turn @get:C @get:[A B] into @get:[A B C] is that oftentimes annotations "belong together", like
@JvmName("frameColDataFrameKProperty") and @Suppress("INAPPLICABLE_JVM_NAME"). In this case it makes not so much to merge with a separate @Deprecated annotation, for instance.

That said, I'm not 100% sure how some of these Spring examples should be linted:

@MustBeDocumented
@Inherited
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
@Retention(AnnotationRetention.RUNTIME)
annotation class ApiKeySecured(val mandatory: Boolean = true)

or

@NotNull(message = "can't be missing")
@Size(min = 1, message = "can't be empty")
@Pattern(
    regexp = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$",
    message = "must be a valid email",
)
var email: String?

[paul-dingemans]

Personally, I didn't even know this notation was possible:

Yeah, I recognize that feeling. I am regularly surprised what is potentially possible with Kotlin. It keeps maintaining ktlint quite interesting though.

// `@[]` are put at the bottom, sorted by width, inside ordered lexicographically

What do you mean with "sorted by width"? Do you mean that @field:[] should go after @set"[]? Is that just because of esthetics?
The current set of "use-site" targets is: file, field, property, get, set, all, receiver, param, setparam, delegate. I would expect that for developers, it is simpler to see the logic of alphabetic sorting, compared to sorting on length of the "use-site" target.
Sort on length of "use-site" target:

@all:[A J]
@get:[C K]
@set:[B]
@file:[L]
@field:[F]
@param:[M N]
@delegate:[E]
@property:[O Q]
@receiver:[G P]
@setparam:[H I]
val string: String

Sort on "use-site" target:

@all:[A J]
@delegate:[E]
@field:[F]
@file:[L]
@get:[C K]
@param:[M N]
@property:[O Q]
@receiver:[G P]
@set:[B]
@setparam:[H I]
val string: String

CurrentIy, annotations with parameters (@Suppress("INAPPLICABLE_JVM_NAME")) are always placed on a separate line. I don't know whether they can be used inside a [] block.

That said, I'm not 100% sure how some of these Spring examples should be linted:

@MustBeDocumented
@Inherited
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
@Retention(AnnotationRetention.RUNTIME)
annotation class ApiKeySecured(val mandatory: Boolean = true)

or

@NotNull(message = "can't be missing")
@Size(min = 1, message = "can't be empty")
@Pattern(
    regexp = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$",
    message = "must be a valid email",
)
var email: String?

I would prefer to sort them alphabetical as well. But I probably would also add a property that contains an ordered list of annotation that will be placed for any annotation that is not included in this list. So for example, if the property contains @Target,@Retention,@Pattern then the examples above are formatted as:

@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
@Retention(AnnotationRetention.RUNTIME)
@Inherited
@MustBeDocumented
annotation class ApiKeySecured(val mandatory: Boolean = true)

and

@Pattern(
    regexp = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$",
    message = "must be a valid email",
)
@NotNull(message = "can't be missing")
@Size(min = 1, message = "can't be empty")
var email: String?

[Jolanrensen]

What do you mean with "sorted by width"? Do you mean that @field:[] should go after @set:[]? Is that just because of esthetics?

I meant @set:[annotation1 annotation2] should be sorted above @field:[someSuperDuperVeryLongAnnotation], as the second one is wider. It looks a bit prettier to me. Of course, if alphabetical makes more sense, that's also fine by me.

CurrentIy, annotations with parameters (@Suppress("INAPPLICABLE_JVM_NAME")) are always placed on a separate line. I don't know whether they can be used inside a [] block.

They definitely can be put inside [] :)

But I probably would also add a property that contains an ordered list of annotation that will be placed for any annotation that is not included in this list

I'm not entirely sure what you mean by this sentence. Some sort of common annotation order?

[paul-dingemans]

I'm not entirely sure what you mean by this sentence. Some sort of common annotation order?

Yes, a configurable way to order annotations which are not grouped by "use site" target. I guess that some people really find it important that some annotation always come before some other annotations. By default this annotation-order property is left empty. Annotations without "use site" target are alphabetically sorted.

Default:

@AnnotationA
@AnnotationB
@AnnotationC
@AnnotationD

If the annotation order property is set to "AnnotationC,AnnotationB" then the result becomes:

@AnnotationC
@AnnotationB
@AnnotationA
@AnnotationD

I don't think that makes sense for the order of annotations between [].