Kdoc order (#770)

* Kdoc order

### What's done:
   Rewrote algorithm and added tests

diktat-rules/src/main/kotlin/org/cqfn/diktat/ruleset/rules/chapter2/kdoc/KdocFormatting.kt

@@ -170,7 +170,7 @@ class KdocFormatting(configRules: List<RulesConfig>) : DiktatRule(
         }
     )
 
-    @Suppress("UnsafeCallOnNullableType")
+    @Suppress("UnsafeCallOnNullableType", "TOO_LONG_FUNCTION")
     private fun checkBasicTagsOrder(node: ASTNode) {
         val kdocTags = node.kDocTags()
         // distinct basic tags which are present in current KDoc, in proper order
@@ -202,10 +202,13 @@ class KdocFormatting(configRules: List<RulesConfig>) : DiktatRule(
                     .filter { basicTagsOrdered.contains(it.knownTag) }
                     .map { it.node }
 
-                basicTagsOrdered.forEachIndexed { index, tag ->
-                    val tagNode = kdocTags.find { it.knownTag == tag }!!.node
-                    kdocSection.addChild(tagNode.clone() as CompositeElement, basicTagChildren[index])
-                    kdocSection.removeChild(basicTagChildren[index])
+                val correctKdocOrder = basicTags
+                    .sortedBy { basicTagsOrdered.indexOf(it.knownTag) }
+                    .map { it.node }
+
+                basicTagChildren.mapIndexed { index, astNode ->
+                    kdocSection.addChild(correctKdocOrder[index].clone() as CompositeElement, astNode)
+                    kdocSection.removeChild(astNode)
                 }
             }
         }

diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/chapter2/KdocFormattingFixTest.kt

@@ -50,4 +50,10 @@ class KdocFormattingFixTest : FixTestBase("test/paragraph2/kdoc/", ::KdocFormatt
     fun `KdocFormatting - all warnings`() {
         fixAndCompare("KdocFormattingFullExpected.kt", "KdocFormattingFullTest.kt")
     }
+
+    @Test
+    @Tags(Tag(WarningNames.KDOC_NO_DEPRECATED_TAG), Tag(WarningNames.KDOC_NO_NEWLINES_BETWEEN_BASIC_TAGS))
+    fun `KdocFormatting - sort order`() {
+        fixAndCompare("KdocFormattingOrderExpected.kt", "KdocFormattingOrderTest.kt")
+    }
 }

diktat-rules/src/test/kotlin/org/cqfn/diktat/ruleset/smoke/DiktatSmokeTest.kt

@@ -8,6 +8,7 @@ import org.cqfn.diktat.ruleset.constants.Warnings.EMPTY_BLOCK_STRUCTURE_ERROR
 import org.cqfn.diktat.ruleset.constants.Warnings.FILE_NAME_MATCH_CLASS
 import org.cqfn.diktat.ruleset.constants.Warnings.HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE
 import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_NO_EMPTY_TAGS
+import org.cqfn.diktat.ruleset.constants.Warnings.KDOC_WITHOUT_PARAM_TAG
 import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_CLASS_ELEMENTS
 import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_ON_FUNCTION
 import org.cqfn.diktat.ruleset.constants.Warnings.MISSING_KDOC_TOP_LEVEL
@@ -160,7 +161,11 @@ class DiktatSmokeTest : FixTestBase("test/smoke/src/main/kotlin",
     fun `smoke test #2`() {
         fixAndCompare("Example2Expected.kt", "Example2Test.kt")
         unfixedLintErrors.assertEquals(
-            LintError(1, 1, "$DIKTAT_RULE_SET_ID:header-comment", "${HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE.warnText()} there are 2 declared classes and/or objects", false)
+            LintError(1, 1, "$DIKTAT_RULE_SET_ID:header-comment", "${HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE.warnText()} there are 2 declared classes and/or objects", false),
+            LintError(15, 23, "$DIKTAT_RULE_SET_ID:kdoc-methods",
+                "${KDOC_WITHOUT_PARAM_TAG.warnText()} createWithFile (containerName)", true),
+            LintError(31, 13, "$DIKTAT_RULE_SET_ID:empty-block-structure",
+                "${EMPTY_BLOCK_STRUCTURE_ERROR.warnText()} empty blocks are forbidden unless it is function with override keyword", false)
         )
     }
 

diktat-rules/src/test/resources/test/paragraph2/kdoc/KdocFormattingOrderExpected.kt

@@ -0,0 +1,17 @@
+package test.paragraph2.kdoc
+
+/**
+ * Creates a docker container with [file], prepared to execute it
+ *
+ * @param runConfiguration a [RunConfiguration] for the supplied binary
+ * @param file a file that will be included as an executable
+ * @param resources additional resources
+ * @return id of created container or null if it wasn't created
+ * @throws DockerException if docker daemon has returned an error
+ * @throws DockerException if docker daemon has returned an error
+ * @throws RuntimeException if an exception not specific to docker has occurred
+ */
+internal fun createWithFile(runConfiguration: RunConfiguration,
+                            containerName: String,
+                            file: File,
+                            resources: Collection<File> = emptySet()): String {}

diktat-rules/src/test/resources/test/paragraph2/kdoc/KdocFormattingOrderTest.kt

@@ -0,0 +1,17 @@
+package test.paragraph2.kdoc
+
+/**
+ * Creates a docker container with [file], prepared to execute it
+ *
+ * @param runConfiguration a [RunConfiguration] for the supplied binary
+ * @param file a file that will be included as an executable
+ * @param resources additional resources
+ * @throws DockerException if docker daemon has returned an error
+ * @throws DockerException if docker daemon has returned an error
+ * @throws RuntimeException if an exception not specific to docker has occurred
+ * @return id of created container or null if it wasn't created
+ */
+internal fun createWithFile(runConfiguration: RunConfiguration,
+                            containerName: String,
+                            file: File,
+                            resources: Collection<File> = emptySet()): String {}

diktat-rules/src/test/resources/test/smoke/src/main/kotlin/Example2Expected.kt

@@ -15,6 +15,23 @@ private class TestException : Exception()
 /* this class is unused */
 // private class Test : RuntimeException()
 
+/**
+ * Creates a docker container with [file], prepared to execute it
+ *
+ * @param runConfiguration a [RunConfiguration] for the supplied binary
+ * @param file a file that will be included as an executable
+ * @param resources additional resources
+ * @param containerName
+ * @return id of created container or null if it wasn't created
+ * @throws DockerException if docker daemon has returned an error
+ * @throws DockerException if docker daemon has returned an error
+ * @throws RuntimeException if an exception not specific to docker has occurred
+ */
+internal fun createWithFile(runConfiguration: RunConfiguration,
+                            containerName: String,
+                            file: File,
+                            resources: Collection<File> = emptySet()) {}
+
 private fun foo(node: ASTNode) {
     when (node.elementType) {
         CLASS, FUN, PRIMARY_CONSTRUCTOR, SECONDARY_CONSTRUCTOR -> checkAnnotation(node)

diktat-rules/src/test/resources/test/smoke/src/main/kotlin/Example2Test.kt

@@ -11,6 +11,22 @@ private class Test : Exception()
 /*    this class is unused */
 //private class Test : RuntimeException()
 
+/**
+ * Creates a docker container with [file], prepared to execute it
+ *
+ * @param runConfiguration a [RunConfiguration] for the supplied binary
+ * @param file a file that will be included as an executable
+ * @param resources additional resources
+ * @throws DockerException if docker daemon has returned an error
+ * @throws DockerException if docker daemon has returned an error
+ * @throws RuntimeException if an exception not specific to docker has occurred
+ * @return id of created container or null if it wasn't created
+ */
+internal fun createWithFile(runConfiguration: RunConfiguration,
+                            containerName: String,
+                            file: File,
+                            resources: Collection<File> = emptySet()) {}
+
 private fun foo (node: ASTNode) {
     when (node.elementType) {
         CLASS, FUN, PRIMARY_CONSTRUCTOR, SECONDARY_CONSTRUCTOR -> checkAnnotation(node)
@@ -24,4 +40,4 @@ private fun foo (node: ASTNode) {
         foo()
 
     setOf<Object>(IOException(), Properties(), LoggerFactory())
-}
+}