Formulate rule/documentation descriptions consistently (#4416)

* Formulate rule/documentation descriptions consistently

reference #4384

* Apply suggestion for missing license text msg

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/AbsentOrWrongFileLicense.kt

@@ -24,7 +24,7 @@ class AbsentOrWrongFileLicense(config: Config = Config.empty) : Rule(config) {
     override val issue = Issue(
         id = RULE_NAME,
         severity = Severity.Maintainability,
-        description = "License text is absent or incorrect in the file.",
+        description = "License text is absent or incorrect.",
         debt = Debt.FIVE_MINS
     )
 

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/CommentOverPrivateProperty.kt

@@ -15,16 +15,16 @@ import org.jetbrains.kotlin.psi.KtProperty
  * Private properties should be named in a self-explanatory way and readers of the code should be able to understand
  * why the property exists and what purpose it solves without the comment.
  *
- * Instead of simply removing the comment to solve this issue prefer renaming the property to a more self-explanatory
- * name. If this property is inside a bigger class it could make senes to refactor and split up the class. This can
+ * Instead of simply removing the comment to solve this issue, prefer renaming the property to a more self-explanatory
+ * name. If this property is inside a bigger class, it makes sense to refactor and split up the class. This can
  * increase readability and make the documentation obsolete.
  */
 class CommentOverPrivateProperty(config: Config = Config.empty) : Rule(config) {
 
     override val issue = Issue(
         "CommentOverPrivateProperty",
         Severity.Maintainability,
-        "Private properties should be named such that they explain themselves even without a comment.",
+        "Private properties should be named in a self-explanatory manner without the need for a  comment.",
         Debt.TWENTY_MINS
     )
 

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/DeprecatedBlockTag.kt

@@ -42,8 +42,8 @@ class DeprecatedBlockTag(config: Config = Config.empty) : Rule(config) {
     override val issue = Issue(
         "DeprecatedBlockTag",
         Severity.Defect,
-        "Do not use the @deprecated block tag, which is not supported by KDoc. " +
-            "Use the @Deprecated annotation instead.",
+        "Do not use the `@deprecated` block tag, which is not supported by KDoc. " +
+            "Use the `@Deprecated` annotation instead.",
         Debt.FIVE_MINS
     )
 

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/EndOfSentenceFormat.kt

@@ -22,7 +22,7 @@ class EndOfSentenceFormat(config: Config = Config.empty) : Rule(config) {
     override val issue = Issue(
         javaClass.simpleName,
         Severity.Maintainability,
-        "The first sentence in a KDoc comment should end with correct punctuation.",
+        "The first sentence in a KDoc comment should end with proper punctuation or with a correct URL.",
         Debt.FIVE_MINS
     )
 

detekt-rules-documentation/src/main/kotlin/io/gitlab/arturbosch/detekt/rules/documentation/OutdatedDocumentation.kt

@@ -24,7 +24,7 @@ import org.jetbrains.kotlin.psi.psiUtil.allChildren
 import org.jetbrains.kotlin.psi.psiUtil.isPropertyParameter
 
 /**
- * This rule will report any class, function or constructor with KDoc that does not match declaration signature.
+ * This rule will report any class, function or constructor with KDoc that does not match the declaration signature.
  * If KDoc is not present or does not contain any @param or @property tags, rule violation will not be reported.
  * By default, both type and value parameters need to be matched and declarations orders must be preserved. You can
  * turn off these features using configuration options.
@@ -66,7 +66,7 @@ class OutdatedDocumentation(config: Config = Config.empty) : Rule(config) {
     override val issue = Issue(
         javaClass.simpleName,
         Severity.Maintainability,
-        "KDoc should match actual function or class signature",
+        "KDoc comments should match the actual function or class signature",
         Debt.TEN_MINS
     )