Early break caused by @

[davidtorosyan]

Unexpected break when there’s a @ prefixed word

Before:

/**
 * aa aa aa aa aa @aa
 */
fun foo() = Unit

/**
 * aa aa aa aa aa baa
 */
fun foo() = Unit

And after:

/**
 * aa aa aa aa
 * aa @aa
 */
fun foo() = Unit

/**
 * aa aa aa aa aa
 * baa
 */
fun foo() = Unit

Using v1.5.1 with:

--max-line-width 20 --max-comment-width 20

[davidtorosyan]

Discussed over email, this is intentional to avoid putting @ at the start of a line.

Before:

/**
 * This @doc will @look @quite odd @because @of @breaks
 */
fun foo() = Unit

After:

/**
 * This @doc
 * will @look @quite
 * odd @because @of @breaks
 */
fun foo() = Unit

@tnorbye I think you can close as not a bug, but I wanted to suggest one other idea: escaping the @ with backticks. Here's how that might look:

/**
 * This @doc will
 * `@look` @quite
 * odd @because
 * `@of` @breaks
 */
fun foo() = Unit

I think there's pros and cons to either approach, so the current one is probably fine.

[tnorbye]

Adding backticks around the symbols would change the appearance of the rendered doc (it would be surrounded by <code> in the HTML). This probably what the user wanted anyway, but maybe it's a little controversial?

[davidtorosyan]

See my argument here for why it's okay to change the appearance in some cases...

but I agree that it's probably overkill in this case.

[tnorbye]

My fear is that attempting to figure out code may be incorrect. E.g. if I see the text

annotate with @CheckReturnValue

it's probably right to change this to

annotate with `@CheckReturnValue`

But what if it's something more complicated, where the code symbol starts either further to the left or ends further to the right; what heuristics can we use to figure out where it begins and ends??

For example, describing how to use a @ReplaceWith annotation in Kotlin:

For more graceful handling, try annotating with something like @Deprecated(message = "unused", replaceWith = ReplaceWith(expression = "cookie"))

Here, I can't just search for the first whitespace (the end of the "symbol). I should really try to find the end -- perhaps by balancing parentheses. But what if there's a confusing message in the string literal message which throws this off?

Or since this isn't code, what if some code is omittted, e.g. the message was something like "Add @Deprecated(message = "unused", ... and so on."

I think heuristic here would be fine for a quickfix but I'm slightly more worried about doing it in an enforced way because it's much more imprecise than the kinds of transformations we do to day (bold to bold, etc).

Feel free to file a request for this enhancement! I'll close this specific bug out as working as intended.