search

tnorbye / kdoc-formatter

Reformats Kotlin KDoc comments, reflowing text and other cleanup, both via IDE plugin and command line utility
Apache License 2.0
73 stars 2 forks source link

Line overrun when using closed-open interval notation #84

Closed nreid260 closed 1 year ago

nreid260 commented 1 year ago

The following KDoc formats in an unfortunate way:

  /**
   * Input is a float in range
   * [0, 1) where 0 is fully settled and 1 is dismissed. Will be continue to be called after the user's finger has lifted. Will not be called for if not dismissible.
   */

It seems that the [ begins a markdown link, which is never closed and so consumes the rest of the text in an unbreakable line. This is in contrast to the "human" interpretation, where ) terminates a numeric interval.

Probably, this is a limitation of trying to use markdown for code comments, and the solution is to have the user add an escape \[.

tnorbye commented 1 year ago

This should be fixed in 1.5.8. (I'm also trying to put it into ktfmt; https://github.com/facebook/ktfmt/pull/372 )

nreid260 commented 1 year ago

Will this introduce ambiguity with other tools (e.g. Dokka)? It might be better to force users to insert escapes, if they'll get weird results otherwise.

tnorbye commented 1 year ago

I did an experiment and Dokka seems to also ignore unterminated link texts.

In case it's useful, the way I'm doing these experiments is to have a checkout of the dokka git repo, examples/gradle/dokka-gradle-example/src/main/kotlin/demo/HelloWorld.kt and then I run

$ ./gradlew dokkaHtml
$ open ./build/dokka/html/\-dokka\ \-gradle\ \-example/\[root\]/index.html
tnorbye commented 1 year ago

Overall though, is there a reporting API in ktfmt to report problems with the source code? I'm thinking I should add that here; there are a number of cases where we can tell the markup is wrong, but we can't auto fix it -- and in those cases it would be nice to alert the user.