@param with brackets is not supported

[davidtorosyan]

@param with brackets is not supported

Before:

/**
 * Summary
 * @param param1 some value
 * @param[param2] another value
 */
fun foo() = Unit

After:

/**
 * Summary
 *
 * @param param1 some value @param[param2] another value
 */
fun foo() = Unit

Using v1.5.4 with default options.

Note that the docs say the following:

To better separate the parameter name from the description, if you prefer, you can enclose the name of the parameter in brackets.

[tnorbye]

I've fixed this (not yet checked in). But should we have an opinion on whether things should be formatted this way, or just preserve what the user has done? For example, if at least one parameter doc has been written that way, should they all be converted to the same?

[davidtorosyan]

I'd vote to preserve what the user has done. They're both called out as valid syntax, so I see no reason to prefer one over the other.

[tnorbye]

My reasoning is that kdoc-formatter (like ktfmt and javaformatter etc) is pretty opinionated -- it decides exactly where there should be newlines, where there shouldn't be, where text must be broken, etc etc. To avoid having style discussion in code reviews, or having individual preferences leak through such that you end up with an inconsistently formatted codebase.

[tnorbye]

(it also seems like a very little used convention; I grepped for @param[ through a bunch of codebases and the only cases I found were test cases in the Kotlin and Dokka sources :-) )

[davidtorosyan]

Good point! Changing my vote to converge kdocs on the @param name syntax. :)

[tnorbye]

This is fixed in 1.5.5 (and it does convert to the canonical format as discussed).