Treat KDoc @propertys as special types of @params, fixes #431

facebook · Aug 4, 2024 · 0725707 · 0725707
1 parent 94bb2fa
commit 0725707
Show file tree

Hide file tree

Showing 5 changed files with 51 additions and 14 deletions.
diff --git a/core/src/main/java/com/facebook/ktfmt/kdoc/ParagraphListBuilder.kt b/core/src/main/java/com/facebook/ktfmt/kdoc/ParagraphListBuilder.kt
@@ -571,18 +571,20 @@ class ParagraphListBuilder(
     return when {
       isPriority -> -1
       tag.startsWith("@param") -> 0
+      tag.startsWith("@property") -> 0
+      // @param and @property must be sorted by parameter order
+      // a @property is dedicated syntax for a main constructor @param that also sets a class property
       tag.startsWith("@return") -> 1
       tag.startsWith("@constructor") -> 2
       tag.startsWith("@receiver") -> 3
-      tag.startsWith("@property") -> 4
-      tag.startsWith("@throws") -> 5
-      tag.startsWith("@exception") -> 6
-      tag.startsWith("@sample") -> 7
-      tag.startsWith("@see") -> 8
-      tag.startsWith("@author") -> 9
-      tag.startsWith("@since") -> 10
-      tag.startsWith("@suppress") -> 11
-      tag.startsWith("@deprecated") -> 12
+      tag.startsWith("@throws") -> 4
+      tag.startsWith("@exception") -> 5
+      tag.startsWith("@sample") -> 6
+      tag.startsWith("@see") -> 7
+      tag.startsWith("@author") -> 8
+      tag.startsWith("@since") -> 9
+      tag.startsWith("@suppress") -> 10
+      tag.startsWith("@deprecated") -> 11
       else -> 100 // custom tags
     }
   }

diff --git a/core/src/main/java/com/facebook/ktfmt/kdoc/Utilities.kt b/core/src/main/java/com/facebook/ktfmt/kdoc/Utilities.kt
@@ -139,19 +139,19 @@ fun String.isKDocTag(): Boolean {
 }
 
 /**
- * If this String represents a KDoc `@param` tag, returns the corresponding parameter name,
+ * If this String represents a KDoc tag named [tag], returns the corresponding parameter name,
  * otherwise null.
  */
-fun String.getParamName(): String? {
+fun String.getTagName(tag: String): String? {
   val length = this.length
   var start = 0
   while (start < length && this[start].isWhitespace()) {
     start++
   }
-  if (!this.startsWith("@param", start)) {
+  if (!this.startsWith(tag, start)) {
     return null
   }
-  start += "@param".length
+  start += tag.length
 
   while (start < length) {
     if (this[start].isWhitespace()) {
@@ -187,6 +187,12 @@ fun String.getParamName(): String? {
   return null
 }
 
+/**
+ * If this String represents a KDoc `@param` or `@property` tag, returns the corresponding parameter
+ * name, otherwise null.
+ */
+fun String.getParamName(): String? = getTagName("@param") ?: getTagName("@property")
+
 private fun getIndent(start: Int, lookup: (Int) -> Char): String {
   var i = start - 1
   while (i >= 0 && lookup(i) != '\n') {

diff --git a/core/src/test/java/com/facebook/ktfmt/format/FormatterTest.kt b/core/src/test/java/com/facebook/ktfmt/format/FormatterTest.kt
@@ -1356,8 +1356,8 @@ class FormatterTest {
             | * Old {@link JavaDocLink} that gets removed.
             | *
             | * @param unused [Param]
-            | * @return [Unit] as [ReturnedValue]
             | * @property JavaDocLink [Param]
+            | * @return [Unit] as [ReturnedValue]
             | * @throws AnException
             | * @throws AnException
             | * @exception Sample.SampleException

diff --git a/core/src/test/java/com/facebook/ktfmt/kdoc/KDocFormatterTest.kt b/core/src/test/java/com/facebook/ktfmt/kdoc/KDocFormatterTest.kt
@@ -3145,6 +3145,34 @@ class KDocFormatterTest {
             .trimIndent())
   }
 
+  @Test
+  fun testPropertiesAreParams() {
+    val source =
+        """
+            /**
+             * @param bar lorem ipsum
+             * @property baz dolor sit
+             * @property foo amet, consetetur
+             */
+            """
+            .trimIndent()
+    checkFormatter(
+        FormattingTask(
+            KDocFormattingOptions(72, 72),
+            source.trim(),
+            initialIndent = "    ",
+            orderedParameterNames = listOf("foo", "bar", "baz"),
+        ),
+        """
+            /**
+             * @property foo amet, consetetur
+             * @param bar lorem ipsum
+             * @property baz dolor sit
+             */
+            """
+            .trimIndent())
+  }
+
   @Test
   fun testKnit() {
     // Some tests for the knit plugin -- https://github.com/Kotlin/kotlinx-knit

diff --git a/core/src/test/java/com/facebook/ktfmt/kdoc/UtilitiesTest.kt b/core/src/test/java/com/facebook/ktfmt/kdoc/UtilitiesTest.kt
@@ -101,6 +101,7 @@ class UtilitiesTest {
     assertThat("@param[foo]".getParamName()).isEqualTo("foo")
     assertThat("@param  [foo]".getParamName()).isEqualTo("foo")
     assertThat("@param ".getParamName()).isNull()
+    assertThat("@property foo".getParamName()).isEqualTo("foo")
   }
 
   @Test