diff --git a/core/src/main/java/com/facebook/ktfmt/kdoc/ParagraphListBuilder.kt b/core/src/main/java/com/facebook/ktfmt/kdoc/ParagraphListBuilder.kt index 592e207b..ea0160cc 100644 --- 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 index 597a2858..4b0f9ec4 100644 --- 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 index 8f424f02..35e2631d 100644 --- 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 index 292d726a..2fa3cb6e 100644 --- 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 index 0bdc7057..75b4320a 100644 --- 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