1.6.4

CHANGELOG.md

@@ -2,20 +2,27 @@
 
 # KDoc Formatter Changelog
 
-## [1.6.3]
+## [1.6.4]
+- Switch continuation indent from 4 to 3. (IntelliJ's Dokka preview
+  treats an indent of 4 or more as preformatted text even on a continued
+  line; Dokka itself (and Markdown) does not.
+- Add ability to override the continuation indent in the IDE plugin
+  settings.
+- Don't reorder `@sample` tags (backported
+  https://github.com/facebook/ktfmt/issues/406)
 
+## [1.6.3]
 - Mark plugin as compatible with K2
 
 ## [1.6.2]
-
 - IDE plugin update only: Compatibility with IntelliJ 2024.1 EAP.
 
 ## [1.6.1]
 - IDE plugin update only.
 
 ## [1.6.0]
-- Updated dependencies and fixed a few minor bugs, including
-  issue 398 from ktfmt.
+- Updated dependencies and fixed a few minor bugs, including issue 398
+  from ktfmt.
 
 ## [1.5.9]
 - Compatibility with IntelliJ 2023.1
@@ -234,4 +241,4 @@
 - Adds hanging indents for ordered and unordered indents.
 - Cleans up the double spaces left by the IntelliJ "Convert to Kotlin"
   action right before the closing comment token.
-- Removes trailing spaces.
+- Removes trailing spaces.

README.md

@@ -120,7 +120,7 @@ Options:
 @<filename>
      Read filenames from file.
 
-kdoc-formatter: Version 1.6.3
+kdoc-formatter: Version 1.6.4
 https://github.com/tnorbye/kdoc-formatter
 ```
 
@@ -177,9 +177,9 @@ buildscript {
         maven { url '/path/to/m2' }
     }
     dependencies {
-        classpath "com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.3"
+        classpath "com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.4"
         // (Sorry about the vanity URL --
-        // I tried to get kdoc-formatter:kdoc-formatter:1.6.3 but that
+        // I tried to get kdoc-formatter:kdoc-formatter:1.6.4 but that
         // didn't meet the naming requirements for publishing:
         // https://issues.sonatype.org/browse/OSSRH-63191)
     }
@@ -199,7 +199,7 @@ buildscript {
         maven { url = uri("/path/to/m2") }
     }
     dependencies {
-        classpath("com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.3")
+        classpath("com.github.tnorbye.kdoc-formatter:kdocformatter:1.6.4")
     }
 }
 plugins {

build.gradle

@@ -18,7 +18,7 @@ buildscript {
 plugins {
     id 'java'
     id 'org.jetbrains.kotlin.jvm' version '2.0.0'
-    id 'com.ncorti.ktfmt.gradle' version '0.18.0'
+    id 'com.ncorti.ktfmt.gradle' version '0.19.0'
 }
 
 group 'kdocformatter'

cli/src/main/kotlin/kdocformatter/cli/KDocFileFormattingOptions.kt

@@ -148,6 +148,15 @@ class KDocFileFormattingOptions {
         }
       }
 
+      if (files.size == 1 && files[0].isFile) {
+        // If you directly try to format a Markdown file, don't require specifying
+        // the flag for that.
+        val path = files[0].path
+        if (path.endsWith(".md") || path.endsWith(".md.html")) {
+          options.includeMd = true
+        }
+      }
+
       if ((options.gitHead || options.gitStaged) && files.isNotEmpty()) {
         // Delayed initialization because the git path and the paths to the
         // repository is typically specified after this flag
@@ -237,7 +246,8 @@ class KDocFileFormattingOptions {
                   """
                 Move KDoc tags to the end of comments, and order them in a canonical
                 order (@param before @return, and so on)""",
-              "--no-order-doc-tags" to """
+              "--no-order-doc-tags" to
+                  """
                 Do not move or reorder KDoc tags""",
               "--include-block-comments" to
                   """
@@ -257,7 +267,8 @@ class KDocFileFormattingOptions {
                   """
                 Line range(s) to format, like 5:10 (1-based; default is all). Can be
                 specified multiple times.""",
-              "--include-md-files" to """
+              "--include-md-files" to
+                  """
                 Format markdown (*.md) files""",
               "--greedy" to
                   """
@@ -267,13 +278,17 @@ class KDocFileFormattingOptions {
                   """
                 Prints the paths of the files whose contents would change if the
                 formatter were run normally.""",
-              "--quiet, -q" to """
+              "--quiet, -q" to
+                  """
                 Quiet mode""",
-              "--verbose, -v" to """
+              "--verbose, -v" to
+                  """
                 Verbose mode""",
-              "--help, -help, -h" to """
+              "--help, -help, -h" to
+                  """
                 Print this usage statement.""",
-              "@<filename>" to """
+              "@<filename>" to
+                  """
                 Read filenames from file.""")
 
       val fileOptions = KDocFileFormattingOptions()

gradle-plugin/build.gradle

@@ -21,7 +21,7 @@ plugins {
     id 'java-gradle-plugin'
     id 'maven-publish'
     id 'com.gradle.plugin-publish' version '0.9.10'
-    id 'com.ncorti.ktfmt.gradle' version '0.18.0'
+    id 'com.ncorti.ktfmt.gradle' version '0.19.0'
 }
 
 // https://issues.sonatype.org/browse/OSSRH-63191

ide-plugin/CHANGELOG.md

@@ -2,50 +2,56 @@
 
 # KDoc Formatter Plugin Changelog
 
-## [1.6.3]
+## [1.6.4]
+- Switch continuation indent from 4 to 3. (IntelliJ's Dokka preview
+  treats an indent of 4 or more as preformatted text even on a continued
+  line; Dokka itself (and Markdown) does not.
+- Add ability to override the continuation indent in the IDE plugin
+  settings.
+- Don't reorder `@sample` tags (backported
+  https://github.com/facebook/ktfmt/issues/406)
 
+## [1.6.3]
 - Compatibility with IntelliJ 2024.2 EAP
 - Mark plugin as compatible with K2
 
 ## [1.6.2]
-
 - Compatibility with IntelliJ 2024.1 EAP.
 
 ## [1.6.1]
-
 - Compatibility with IntelliJ 2023.3 EAP.
 
 ## [1.6.0]
 - Updated dependencies and fixed a few minor bugs, including
-  https://github.com/tnorbye/kdoc-formatter/issues/88
-  as well as issue 398 in ktfmt.
+  https://github.com/tnorbye/kdoc-formatter/issues/88 as well as issue
+  398 in ktfmt.
 
 ## [1.5.9]
 - Compatibility with IntelliJ 2023.1
 
 ## [1.5.8]
 - Fixed a number of bugs:
-  - #84: Line overrun when using closed-open interval notation
-  - More gracefully handle unterminated [] references (for example when
-    comment is using it in things like [closed, open) intervals)
-  - Recognize and convert accidentally capitalized kdoc tags like @See
-  - If you have a [ref] which spans a line such that the # ends up as a
-    new line, don't treat this as a "# heading".
-  - If you're using optimal line breaking and there's a really long,
-    unbreakable word in the paragraph, switch that paragraph over to
-    greedy line breaking (to make the paragraph better balanced since
-    the really long word throws the algorithm off.)
-  - Fix a few scenarios where markup conversion from <p> and </p>
-    wasn't converting everything.
-  - Allow @property[name], not just @param[name]
+   - #84: Line overrun when using closed-open interval notation
+   - More gracefully handle unterminated [] references (for example when
+     comment is using it in things like [closed, open) intervals)
+   - Recognize and convert accidentally capitalized kdoc tags like @See
+   - If you have a [ref] which spans a line such that the # ends up as a
+     new line, don't treat this as a "# heading".
+   - If you're using optimal line breaking and there's a really long,
+     unbreakable word in the paragraph, switch that paragraph over to
+     greedy line breaking (to make the paragraph better balanced since
+     the really long word throws the algorithm off.)
+   - Fix a few scenarios where markup conversion from <p> and </p>
+     wasn't converting everything.
+   - Allow @property[name], not just @param[name]
 - Some minor code cleanup.
 
 ## [1.5.7]
 - Fixed the following bugs:
-   - #76: Preserve newline style (CRLF on Windows)
-   - #77: Preformatting error
-   - #78: Preformatting stability
-   - #79: Replace `{@param name}` with `[name]`
+      - #76: Preserve newline style (CRLF on Windows)
+      - #77: Preformatting error
+      - #78: Preformatting stability
+      - #79: Replace `{@param name}` with `[name]`
 
 ## [1.5.6]
 - Bugfix: the override line width setting was not working
@@ -145,4 +151,4 @@
   width).
 
 ## [1.0.0]
-- Initial version
+- Initial version

ide-plugin/gradle.properties

@@ -12,7 +12,7 @@ pluginUntilBuild = 242.*
 
 # IntelliJ Platform Properties -> https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties
 platformType = IC
-platformVersion = 2023.2
+platformVersion = 2024.1
 #platformVersion = 241.9959-EAP-CANDIDATE-SNAPSHOT
 
 # Plugin Dependencies -> https://plugins.jetbrains.com/docs/intellij/plugin-dependencies.html

ide-plugin/src/main/kotlin/kdocformatter/plugin/KDocOptionsConfigurable.kt

@@ -83,7 +83,7 @@ class KDocOptionsConfigurable :
       separator()
       row {
         label(
-            "Override line widths (if blank or 0, the code style line width or .editorconfig is used) :")
+            "Override line widths (if blank or 0, the code style line width or .editorconfig is used):")
       }
 
       row("Line Width") {
@@ -97,23 +97,39 @@ class KDocOptionsConfigurable :
             .columns(4)
             .trimmedTextValidation(widthValidator)
       }
+
+      separator()
+      row { label("Override continuation indent (@param lists, etc); leave blank to use default:") }
+
+      row("Continuation Indentation") {
+        textField()
+            .bindWidth(state::overrideHangingIndent, -1)
+            .columns(4)
+            .trimmedTextValidation(indentValidator)
+      }
     }
   }
 
-  private fun <T : JTextComponent> Cell<T>.bindWidth(prop: KMutableProperty0<Int>): Cell<T> {
-    return bindWidth(prop.toMutableProperty())
+  private fun <T : JTextComponent> Cell<T>.bindWidth(
+      prop: KMutableProperty0<Int>,
+      useDefault: Int = 0
+  ): Cell<T> {
+    return bindWidth(prop.toMutableProperty(), useDefault)
   }
 
-  // Like bindIntText, but treats blank as 0
-  private fun <T : JTextComponent> Cell<T>.bindWidth(prop: MutableProperty<Int>): Cell<T> {
+  // Like bindIntText, but treats blank as [default]
+  private fun <T : JTextComponent> Cell<T>.bindWidth(
+      prop: MutableProperty<Int>,
+      useDefault: Int = 0
+  ): Cell<T> {
     return bindText(
         getter = {
           val value = prop.get()
-          if (value == 0) "" else value.toString()
+          if (value == useDefault) "" else value.toString()
         },
         setter = { value: String ->
           if (value.isEmpty()) {
-            prop.set(0)
+            prop.set(useDefault)
           } else {
             val v = value.toIntOrNull()
             if (v != null) {
@@ -129,4 +145,11 @@ class KDocOptionsConfigurable :
         value.isNotEmpty() && value.any { digit -> !digit.isDigit() } ||
             (value.toIntOrNull() == null || value.toInt() < 10)
       }
+
+  private val indentValidator: DialogValidation.WithParameter<() -> String> =
+      validationErrorIf<String>("Field must be empty or an integer in the range 0 to 12") {
+        val value = it
+        value.isNotEmpty() && value.any { digit -> !digit.isDigit() } ||
+            (value.toIntOrNull() == null || value.toInt() > 12)
+      }
 }

ide-plugin/src/main/kotlin/kdocformatter/plugin/KDocPluginOptions.kt

@@ -57,6 +57,7 @@ class KDocPluginOptions : PersistentStateComponent<KDocPluginOptions.ComponentSt
 
     var overrideLineWidth: Int = 0
     var overrideCommentWidth: Int = 0
+    var overrideHangingIndent: Int = -1
   }
 
   companion object {

ide-plugin/src/main/kotlin/kdocformatter/plugin/ReformatKDocAction.kt

@@ -393,6 +393,9 @@ fun createFormattingOptions(
     if (state.overrideCommentWidth > 0) {
       maxCommentWidth = state.overrideCommentWidth
     }
+    if (state.overrideHangingIndent >= 0) {
+      hangingIndent = state.overrideHangingIndent
+    }
     if (!state.maxCommentWidthEnabled) {
       maxCommentWidth = maxLineWidth
     }

library/src/main/kotlin/com/facebook/ktfmt/kdoc/KDocFormattingOptions.kt

@@ -41,7 +41,7 @@ class KDocFormattingOptions(
     /**
      * Limit comment to be at most [maxCommentWidth] characters even if more would fit on the line.
      */
-    var maxCommentWidth: Int = min(maxLineWidth, 72)
+    var maxCommentWidth: Int = min(maxLineWidth, 72),
 ) {
   /** Whether to collapse multi-line comments that would fit on a single line into a single line. */
   var collapseSingleLine: Boolean = true
@@ -63,7 +63,7 @@ class KDocFormattingOptions(
    * more here will result in subsequent lines being interpreted as block formatted by IntelliJ (but
    * not Dokka).
    */
-  var hangingIndent: Int = 4
+  var hangingIndent: Int = 3
 
   /** When there are nested lists etc, how many spaces to indent by. */
   var nestedListIndent: Int = 3

library/src/main/kotlin/com/facebook/ktfmt/kdoc/Paragraph.kt

@@ -425,7 +425,7 @@ class Paragraph(private val task: FormattingTask) {
     }
 
     if (prev == "@sample") {
-      return false // https://github.com/facebookincubator/ktfmt/issues/310
+      return false // https://github.com/facebook/ktfmt/issues/310
     }
 
     if (!word.first().isLetter()) {