diff --git a/diktat-analysis.yml b/diktat-analysis.yml index 5ab0f0885a..0b25fe892f 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: {} # if a class has single constructor, it should be converted to a primary constructor - name: SINGLE_CONSTRUCTOR_SHOULD_BE_PRIMARY enabled: true diff --git a/diktat-rules/src/main/kotlin/generated/WarningNames.kt b/diktat-rules/src/main/kotlin/generated/WarningNames.kt index 159fe3eca0..eec21d4ab9 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 ef17b1f977..1734aa8714 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, "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"), 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..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,10 +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.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 +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.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 @@ -150,7 +151,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 +170,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 0d2b898f74..a61370679e 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: {} # if a class has single constructor, it should be converted to a primary constructor - name: SINGLE_CONSTRUCTOR_SHOULD_BE_PRIMARY enabled: true diff --git a/diktat-rules/src/main/resources/diktat-analysis.yml b/diktat-rules/src/main/resources/diktat-analysis.yml index d18ebca442..9b0ca9ebb6 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: {} # if a class has single constructor, it should be converted to a primary constructor - name: SINGLE_CONSTRUCTOR_SHOULD_BE_PRIMARY 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 ff8ef36a4f..30e9865b60 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|