From c2892ff62a0b8643bd9e9279579c3fc495302441 Mon Sep 17 00:00:00 2001 From: kentr0w Date: Fri, 6 Nov 2020 14:42:38 +0300 Subject: [PATCH 1/3] Confusing warning message in KDOC_NO_CONSTRUCTOR_PROPERTY ### What's done: Created new warning --- diktat-analysis.yml | 4 ++++ diktat-rules/src/main/kotlin/generated/WarningNames.kt | 3 +++ .../kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt | 3 ++- .../org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt | 8 +++----- .../src/main/resources/diktat-analysis-huawei.yml | 4 ++++ diktat-rules/src/main/resources/diktat-analysis.yml | 6 +++++- .../org/cqfn/diktat/ruleset/chapter2/KdocWarnTest.kt | 8 ++++---- info/available-rules.md | 3 ++- 8 files changed, 27 insertions(+), 12 deletions(-) diff --git a/diktat-analysis.yml b/diktat-analysis.yml index b3d835e50c..0f4ea03d3b 100644 --- a/diktat-analysis.yml +++ b/diktat-analysis.yml @@ -326,6 +326,10 @@ - name: KDOC_NO_CONSTRUCTOR_PROPERTY enabled: true configuration: {} +# Checks that KDoc in constructor has property tag but with comment inside constructor +- name: KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT + enabled: true + configuration: {} # Checks if class can be made as data class - name: USE_DATA_CLASS enabled: true diff --git a/diktat-rules/src/main/kotlin/generated/WarningNames.kt b/diktat-rules/src/main/kotlin/generated/WarningNames.kt index 647e2ec6c8..53ba549418 100644 --- a/diktat-rules/src/main/kotlin/generated/WarningNames.kt +++ b/diktat-rules/src/main/kotlin/generated/WarningNames.kt @@ -81,6 +81,9 @@ public object WarningNames { public const val KDOC_NO_CONSTRUCTOR_PROPERTY: String = "KDOC_NO_CONSTRUCTOR_PROPERTY" + public const val KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT: String = + "KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT" + public const val HEADER_WRONG_FORMAT: String = "HEADER_WRONG_FORMAT" public const val HEADER_MISSING_OR_WRONG_COPYRIGHT: String = "HEADER_MISSING_OR_WRONG_COPYRIGHT" diff --git a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt index 3d07080314..74256b95a6 100644 --- a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt +++ b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt @@ -55,7 +55,8 @@ enum class Warnings(private val canBeAutoCorrected: Boolean, private val warn: S KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS(true, "in KDoc there should be exactly one empty line after special tags"), KDOC_NO_EMPTY_TAGS(false, "no empty descriptions in tag blocks are allowed"), KDOC_NO_DEPRECATED_TAG(true, "KDoc doesn't support @deprecated tag, use @Deprecated annotation instead"), - KDOC_NO_CONSTRUCTOR_PROPERTY(true, "replace comment before property with @property tag in KDoc"), + KDOC_NO_CONSTRUCTOR_PROPERTY(true, "add @property tag with description in KDoc"), + KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT(true, "replace comment before property with @property tag in KDoc"), HEADER_WRONG_FORMAT(true, "file header comments should be properly formatted"), HEADER_MISSING_OR_WRONG_COPYRIGHT(true, "file header comment must include copyright information inside a block comment"), WRONG_COPYRIGHT_YEAR(true, "year defined in copyright and current year are different"), diff --git a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt index bf5689a83a..ea9c28a483 100644 --- a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt +++ b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt @@ -4,9 +4,6 @@ import org.cqfn.diktat.common.config.rules.RulesConfig import org.cqfn.diktat.common.config.rules.getCommonConfiguration import org.cqfn.diktat.ruleset.constants.EmitType import org.cqfn.diktat.ruleset.constants.Warnings -import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NO_CONSTRUCTOR_PROPERTY -import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_CLASS_ELEMENTS -import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_TOP_LEVEL import org.cqfn.diktat.ruleset.utils.KotlinParser import org.cqfn.diktat.ruleset.utils.getAllChildrenWithType import org.cqfn.diktat.ruleset.utils.getFileName @@ -40,6 +37,7 @@ import com.pinterest.ktlint.core.ast.ElementType.VAL_KEYWORD import com.pinterest.ktlint.core.ast.ElementType.VAR_KEYWORD import com.pinterest.ktlint.core.ast.ElementType.WHITE_SPACE import com.pinterest.ktlint.core.ast.parent +import org.cqfn.diktat.ruleset.constants.Warnings.* import org.jetbrains.kotlin.com.intellij.lang.ASTNode import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.LeafPsiElement import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.PsiWhiteSpaceImpl @@ -150,7 +148,7 @@ class KdocComments(private val configRules: List) : Rule("kdoc-comm if (prevComment.elementType == KDOC || prevComment.elementType == BLOCK_COMMENT) { handleKdocAndBlock(node, prevComment, kdocBeforeClass, propertyInClassKdoc, propertyInLocalKdoc) } else { - KDOC_NO_CONSTRUCTOR_PROPERTY.warnAndFix(configRules, emitWarn, isFixMode, node.findChildByType(IDENTIFIER)!!.text, prevComment.startOffset, node) { + KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT.warnAndFix(configRules, emitWarn, isFixMode, node.findChildByType(IDENTIFIER)!!.text, prevComment.startOffset, node) { handleCommentBefore(node, kdocBeforeClass, prevComment, propertyInClassKdoc) } } @@ -169,7 +167,7 @@ class KdocComments(private val configRules: List) : Rule("kdoc-comm @Suppress("UnsafeCallOnNullableType") private fun createKdocWithProperty(node: ASTNode, prevComment: ASTNode) { - KDOC_NO_CONSTRUCTOR_PROPERTY.warnAndFix(configRules, emitWarn, isFixMode, prevComment.text, prevComment.startOffset, node) { + KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT.warnAndFix(configRules, emitWarn, isFixMode, prevComment.text, prevComment.startOffset, node) { val classNode = node.parent({ it.elementType == CLASS })!! val newKdocText = if (prevComment.elementType == KDOC) { prevComment.text diff --git a/diktat-rules/src/main/resources/diktat-analysis-huawei.yml b/diktat-rules/src/main/resources/diktat-analysis-huawei.yml index eb9b406278..1641742244 100644 --- a/diktat-rules/src/main/resources/diktat-analysis-huawei.yml +++ b/diktat-rules/src/main/resources/diktat-analysis-huawei.yml @@ -325,6 +325,10 @@ - name: KDOC_NO_CONSTRUCTOR_PROPERTY enabled: true configuration: {} +# Checks that KDoc in constructor has property tag but with comment inside constructor +- name: KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT + enabled: true + configuration: {} # Checks if class can be made as data class - name: USE_DATA_CLASS enabled: true diff --git a/diktat-rules/src/main/resources/diktat-analysis.yml b/diktat-rules/src/main/resources/diktat-analysis.yml index 827ca90ccd..07c50a0f83 100644 --- a/diktat-rules/src/main/resources/diktat-analysis.yml +++ b/diktat-rules/src/main/resources/diktat-analysis.yml @@ -323,10 +323,14 @@ - name: WRONG_OVERLOADING_FUNCTION_ARGUMENTS enabled: true configuration: {} -# Checks that property in constructor doesn't contains comment +# Checks that KDoc in constructor has property tag - name: KDOC_NO_CONSTRUCTOR_PROPERTY enabled: true configuration: {} +# Checks that KDoc in constructor has property tag but with comment inside constructor +- name: KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT + enabled: true + configuration: {} # Checks if class can be made as data class - name: USE_DATA_CLASS enabled: true diff --git a/diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/KdocWarnTest.kt b/diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/KdocWarnTest.kt index 8bf5e1bad6..2c6cb9cea3 100644 --- a/diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/KdocWarnTest.kt +++ b/diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/KdocWarnTest.kt @@ -206,7 +206,7 @@ class KdocWarnTest : LintTestBase(::KdocComments) { } @Test - @Tag(WarningNames.KDOC_NO_CONSTRUCTOR_PROPERTY) + @Tag(WarningNames.KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT) fun `check simple primary constructor with comment`() { lintMethod( """ @@ -221,7 +221,7 @@ class KdocWarnTest : LintTestBase(::KdocComments) { |) { |} """.trimMargin(), - LintError(7, 4, ruleId, "${KDOC_NO_CONSTRUCTOR_PROPERTY.warnText()} name", true) + LintError(7, 4, ruleId, "${KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT.warnText()} name", true) ) } @@ -247,7 +247,7 @@ class KdocWarnTest : LintTestBase(::KdocComments) { } @Test - @Tag(WarningNames.KDOC_NO_CONSTRUCTOR_PROPERTY) + @Tag(WarningNames.KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT) fun `check constructor with comment`() { lintMethod( """ @@ -262,7 +262,7 @@ class KdocWarnTest : LintTestBase(::KdocComments) { | ) { |} """.trimMargin(), - LintError(5, 4, ruleId, "${KDOC_NO_CONSTRUCTOR_PROPERTY.warnText()} name", true) + LintError(5, 4, ruleId, "${KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT.warnText()} name", true) ) } diff --git a/info/available-rules.md b/info/available-rules.md index cab2971467..1b7384438f 100644 --- a/info/available-rules.md +++ b/info/available-rules.md @@ -36,7 +36,8 @@ | 2 | 2.3 | KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS | Check: warns if special tags `@apiNote`, `@implNote`, `@implSpec` don't have exactly one empty line after
Fix: removes redundant lines or adds one | yes | |Handle empty lines without leading asterisk| | 2 | 2.3 | KDOC_NO_EMPTY_TAGS | Check: warns if KDoc tags have empty content | no | || | 2 | 2.3 | KDOC_NO_DEPRECATED_TAG | Check: warns if `@deprecated` is used in KDoc
Fix: adds `@Deprecated` annotation with message, removes tag | yes | |Annotation's `replaceWith` field can be filled too| -| 2 | 2.3 | KDOC_NO_CONSTRUCTOR_PROPERTY | Check: warns if there is comment before property in constructor | yes | -| +| 2 | 2.3 | KDOC_NO_CONSTRUCTOR_PROPERTY | Check: warns if there is no property tag inside KDoc before constructor | yes | -| +| 2 | 2.3 | KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT | Check: warns if there is comment before property in constructor | yes | -| | 2 | 2.5 | KDOC_TRIVIAL_KDOC_ON_FUNCTION | Check: warns if KDoc contains single line with words 'return', 'get' or 'set' | no | - | | 2 | 2.4 | HEADER_WRONG_FORMAT | Checks: warns if there is no newline after header KDoc
Fix: adds newline | yes | |Check if header is on the very top of file. It's hard to determine when it's not.| | 2 | 2.4 | HEADER_MISSING_OR_WRONG_COPYRIGHT | Checks: copyright exists on top of file and is properly formatted (as a block comment)
Fix: adds copyright if it is missing and required | yes |mandatoryCopyright|Allow setting copyright patterns via configuration| From c0689aaa2276b0c60767eb6015099b51c1bdaf24 Mon Sep 17 00:00:00 2001 From: kentr0w Date: Sat, 7 Nov 2020 19:09:38 +0300 Subject: [PATCH 2/3] Confusing warning message in KDOC_NO_CONSTRUCTOR_PROPERTY ### What's done: Made a little prettier --- .../main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt index 74256b95a6..620fc4e8a2 100644 --- a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt +++ b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/constants/Warnings.kt @@ -55,8 +55,8 @@ enum class Warnings(private val canBeAutoCorrected: Boolean, private val warn: S KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS(true, "in KDoc there should be exactly one empty line after special tags"), KDOC_NO_EMPTY_TAGS(false, "no empty descriptions in tag blocks are allowed"), KDOC_NO_DEPRECATED_TAG(true, "KDoc doesn't support @deprecated tag, use @Deprecated annotation instead"), - KDOC_NO_CONSTRUCTOR_PROPERTY(true, "add @property tag with description in KDoc"), - KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT(true, "replace comment before property with @property tag in KDoc"), + KDOC_NO_CONSTRUCTOR_PROPERTY(true, "all properties from the primary constructor should be documented in a @property tag in KDoc"), + KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT(true, "replace comment before property with @property tag in class KDoc"), HEADER_WRONG_FORMAT(true, "file header comments should be properly formatted"), HEADER_MISSING_OR_WRONG_COPYRIGHT(true, "file header comment must include copyright information inside a block comment"), WRONG_COPYRIGHT_YEAR(true, "year defined in copyright and current year are different"), From ee2c059f011a5f59e59775af2cff0d52b5197f2d Mon Sep 17 00:00:00 2001 From: kentr0w Date: Sat, 7 Nov 2020 19:15:12 +0300 Subject: [PATCH 3/3] Confusing warning message in KDOC_NO_CONSTRUCTOR_PROPERTY ### What's done: Removed wildcard --- .../org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt index ea9c28a483..ccccc9821f 100644 --- a/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt +++ b/diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/kdoc/KdocComments.kt @@ -3,7 +3,6 @@ package org.cqfn.diktat.ruleset.rules.kdoc import org.cqfn.diktat.common.config.rules.RulesConfig import org.cqfn.diktat.common.config.rules.getCommonConfiguration import org.cqfn.diktat.ruleset.constants.EmitType -import org.cqfn.diktat.ruleset.constants.Warnings import org.cqfn.diktat.ruleset.utils.KotlinParser import org.cqfn.diktat.ruleset.utils.getAllChildrenWithType import org.cqfn.diktat.ruleset.utils.getFileName @@ -37,7 +36,11 @@ import com.pinterest.ktlint.core.ast.ElementType.VAL_KEYWORD import com.pinterest.ktlint.core.ast.ElementType.VAR_KEYWORD import com.pinterest.ktlint.core.ast.ElementType.WHITE_SPACE import com.pinterest.ktlint.core.ast.parent -import org.cqfn.diktat.ruleset.constants.Warnings.* +import org.cqfn.diktat.ruleset.constants.Warnings +import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NO_CONSTRUCTOR_PROPERTY +import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NO_CONSTRUCTOR_PROPERTY_WITH_COMMENT +import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_TOP_LEVEL +import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_CLASS_ELEMENTS import org.jetbrains.kotlin.com.intellij.lang.ASTNode import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.LeafPsiElement import org.jetbrains.kotlin.com.intellij.psi.impl.source.tree.PsiWhiteSpaceImpl