Final version of white-paper (#655)

* Final version of white-paper ### What's done: Fixed final bugs in wp
saveourtool · Jan 14, 2021 · d34ed1c · d34ed1c · 0pdd · Jan 14, 2021
1 parent 241f45e
commit d34ed1c
Show file tree

Hide file tree

Showing 23 changed files with 749 additions and 432 deletions.
diff --git a/README.md b/README.md
@@ -26,9 +26,9 @@ Now diKTat was already added to the lists of [static analysis tools](https://git
 
 ## See first
 
-|  |  |  |  |
-| --- | --- | --- | --- |
-|[DiKTat codestyle](info/guide/diktat-coding-convention.md)|[Supported Rules](info/available-rules.md) | [Examples of Usage](https://github.com/akuleshov7/diktat-examples) | [Online Demo](https://ktlint-demo.herokuapp.com) | [Whitepaper](wp/wp.pdf) |
+|  |  |  |  |  |
+| --- | --- | --- | --- | --- |
+|[DiKTat codestyle](info/guide/diktat-coding-convention.md)|[Supported Rules](info/available-rules.md) | [Examples of Usage](https://github.com/akuleshov7/diktat-examples) | [Online Demo](https://ktlint-demo.herokuapp.com) | [White Paper](wp/wp.pdf) |
 
 ## Why should I use diktat in my CI/CD?
 

diff --git a/info/buildSrc/src/main/kotlin/org/cqfn/diktat/generation/docs/GenerationAvailableRules.kt b/info/buildSrc/src/main/kotlin/org/cqfn/diktat/generation/docs/GenerationAvailableRules.kt
@@ -18,7 +18,7 @@ fun generateAvailableRules(rootDir: File, wpDir: File) {
         .map { it[2].replace("\\s+".toRegex(), "") to it[5] }
         .forEach { ruleMap[it.first]!!.config = it.second}
     val newText = File(wpDir, "sections/appendix.tex").readLines().toMutableList()
-    newText.removeAll(newText.subList(newText.indexOf("\\section*{Available Rules}") + 1, newText.indexOf("\\lstMakeShortInline[basicstyle=\\ttfamily\\bfseries]`")))
+    newText.removeAll(newText.subList(newText.indexOf("\\section*{Available Rules}") + 1, newText.indexOf("%CodeStyle")))
     var index = newText.indexOf("\\section*{Available Rules}") + 1
     AUTO_TABLE.trimIndent().lines().forEach { newText.add(index++, it) }
     ruleMap.map { it.value }

diff --git a/info/buildSrc/src/main/kotlin/org/cqfn/diktat/generation/docs/GenerationDocs.kt b/info/buildSrc/src/main/kotlin/org/cqfn/diktat/generation/docs/GenerationDocs.kt
@@ -5,6 +5,7 @@ package org.cqfn.diktat.generation.docs
 import java.io.File
 import java.io.PrintWriter
 
+
 /**
  * Adds/updates diktat code style in white paper document.
  */
@@ -22,15 +23,14 @@ fun generateCodeStyle(guideDir: File, wpDir: File) {
     val lines = file.readLines().toMutableList().drop(1)
     tempFile.printWriter().use { writer ->
         val iterator = lines.iterator()
-        writer.writeln("\\lstMakeShortInline[basicstyle=\\ttfamily\\bfseries]`")
+        writer.writeWithoutApostrophe("%CodeStyle")
         while (iterator.hasNext()) {
             val line = iterator.next()
             if (line.contains("## <a name=\"c0\"></a> Preface"))
-                break;
-
+                break
             when {
                 line.startsWith("#") -> {
-                    writer.writeln("\\section*{${line.removePrefix("#").trim()}}")
+                    writer.writeWithoutApostrophe("\\section*{${line.removePrefix("#").trim()}}")
                 }
                 line.startsWith("*") -> {
                     writeTableContentLine(writer, line, 0.5)
@@ -49,8 +49,7 @@ fun generateCodeStyle(guideDir: File, wpDir: File) {
             if (line.contains("<!--")) {
                 // for now there are no multiline comments in our doc
                 continue
-            }
-            if (line.startsWith("#")) {
+            } else if (line.startsWith("#")) {
                 val number = NUMBER_IN_TAG
                         .find(line)
                         ?.value
@@ -64,27 +63,26 @@ fun generateCodeStyle(guideDir: File, wpDir: File) {
                 if (name.isNullOrEmpty() || number.isNullOrEmpty()) {
                     if (number.isNullOrEmpty() && name.isNullOrEmpty()) {
                         when (line.takeWhile { it == '#' }.count()) {
-                            1 -> writer.writeln("""\section*{\textbf{${line.removePrefix("#").trim()}}}""")
-                            2 -> writer.writeln("""\section*{\textbf{${line.removePrefix("##").trim()}}}""")
-                            3 -> writer.writeln("""\subsection*{\textbf{${line.removePrefix("###").trim()}}}""")
-                            4 -> writer.writeln("""\subsubsection*{\textbf{${line.removePrefix("####").trim()}}}${"\n"}\leavevmode\newline""")
+                            1 -> writer.writeWithoutApostrophe("""\section*{\textbf{${line.removePrefix("#").trim()}}}""")
+                            2 -> writer.writeWithoutApostrophe("""\section*{\textbf{${line.removePrefix("##").trim()}}}""")
+                            3 -> writer.writeWithoutApostrophe("""\subsection*{\textbf{${line.removePrefix("###").trim()}}}""")
+                            4 -> writer.writeWithoutApostrophe("""\subsubsection*{\textbf{${line.removePrefix("####").trim()}}}${"\n"}\leavevmode\newline""")
                             else -> {}
                         }
                         continue
                     }
                     error("String starts with # but has no number or name - $line")
                 }
                 when (number.count { it == '.' }) {
-                    0 -> writer.writeln("""\section*{\textbf{$name}}""")
-                    1 -> writer.writeln("""\subsection*{\textbf{$name}}""")
-                    2 -> writer.writeln("""\subsubsection*{\textbf{$name}}${"\n"}\leavevmode\newline""")
+                    0 -> writer.writeWithoutApostrophe("""\section*{\textbf{$name}}""")
+                    1 -> writer.writeWithoutApostrophe("""\subsection*{\textbf{$name}}""")
+                    2 -> writer.writeWithoutApostrophe("""\subsubsection*{\textbf{$name}}${"\n"}\leavevmode\newline""")
                     else -> {}
                 }
-                writer.writeln("\\label{sec:${name.getFirstNumber()}}")
+                writer.writeWithoutApostrophe("\\label{sec:${name.getFirstNumber()}}")
 
                 continue
-            }
-            if (iterator.hasNext() && line.trim().startsWith("```")) {
+            } else if (iterator.hasNext() && line.trim().startsWith("```")) {
                 writer.writeCode("""\begin{lstlisting}[language=Kotlin]""")
                 line = iterator.next()
                 while (!line.trim().startsWith("```")) {
@@ -93,27 +91,25 @@ fun generateCodeStyle(guideDir: File, wpDir: File) {
                 }
                 writer.writeCode("""\end{lstlisting}""")
                 continue
-            }
-
-            if (line.trim().startsWith("|")) {
+            } else if (line.trim().startsWith("|")) {
                 val columnNumber = line.count { it == '|' } - 1
                 val columnWidth: Float = (A4_PAPER_WIDTH / columnNumber)  // For now it makes all column width equal
                 val createTable = "|p{${columnWidth.format(1)}cm}".repeat(columnNumber).plus("|")
-                writer.writeln("""\begin{center}""")
-                writer.writeln("""\begin{tabular}{ $createTable }""")
-                writer.writeln("""\hline""")
+                writer.writeWithoutApostrophe("""\begin{center}""")
+                writer.writeWithoutApostrophe("""\begin{tabular}{ $createTable }""")
+                writer.writeWithoutApostrophe("""\hline""")
                 val columnNames = TABLE_COLUMN_NAMES
                         .findAll(line)
                         .filter { it.value.isNotEmpty() }
                         .map { it.value.trim() }
                         .toList()
                 writer.write(columnNames.joinToString(separator = "&"))
-                writer.writeln("""\\""")
-                writer.writeln("\\hline")
+                writer.writeWithoutApostrophe("""\\""")
+                writer.writeWithoutApostrophe("\\hline")
                 iterator.next()
                 line = iterator.next()
                 while (iterator.hasNext() && line.trim().startsWith("|")) {
-                    writer.writeln(line
+                    writer.writeWithoutApostrophe(line
                             .replace("&", "\\&")
                             .replace('|', '&')
                             .drop(1)
@@ -123,33 +119,48 @@ fun generateCodeStyle(guideDir: File, wpDir: File) {
                             .replace(ANCHORS, ""))
                     line = iterator.next()
                 }
-                writer.writeln("""\hline""")
-                writer.writeln("\\end{tabular}")
-                writer.writeln("\\end{center}")
+                writer.writeWithoutApostrophe("""\hline""")
+                writer.writeWithoutApostrophe("\\end{tabular}")
+                writer.writeWithoutApostrophe("\\end{center}")
             } else {
-                var correctedString = findBoldOrItalicText(BOLD_TEXT, line, FindType.BOLD)
-                correctedString = findBoldOrItalicText(ITALIC_TEXT, correctedString, FindType.ITALIC)
-                correctedString = correctedString.replace(ANCHORS, "")
-                correctedString = correctedString.replace("#", "\\#")
-                correctedString = correctedString.replace("&", "\\&")
-                correctedString = correctedString.replace("_", "\\_")
-                // find backticks should be the last to replace \_ with _
-                correctedString = handleHyperlinks(correctedString)
-                correctedString = findBoldOrItalicText(BACKTICKS_TEXT, correctedString, FindType.BACKTICKS)
-
-                writer.writeln(correctedString)
+                writer.writeWithoutApostrophe(line, false)
             }
         }
     }
     val appendixFileLines = File(wpDir, "sections/appendix.tex")
             .readLines()
-            .takeWhile { it != "\\lstMakeShortInline[basicstyle=\\ttfamily\\bfseries]`" }
+            .takeWhile { it != "%CodeStyle" }
             .toMutableList()
     appendixFileLines.addAll(tempFile.readLines())
     File(wpDir, "sections/appendix.tex").writeText(appendixFileLines.joinToString(separator = "\n"))
     tempFile.delete()
 }
 
+private fun PrintWriter.writeWithoutApostrophe(text: String, isCommand: Boolean = true) {
+    this.writeln(text.replaceApostrophe(isCommand))
+}
+
+private fun String.replaceApostrophe(isCommand: Boolean): String {
+    if (isCommand){
+        return this
+    }
+    var correctedString = this
+    if (correctedString.contains("\\") && (correctedString.contains("""\\[a-zA-Z]""".toRegex()))) {
+        correctedString = correctedString.replace("\\", "\\textbackslash ")
+    }
+    correctedString = correctedString.replace("{", "\\{")
+    correctedString = correctedString.replace("}", "\\}")
+    correctedString = correctedString.replace("_", "\\_")
+    correctedString = correctedString.replace(ANCHORS, "")
+    correctedString = correctedString.replace("#", "\\#")
+    correctedString = correctedString.replace("&", "\\&")
+    correctedString = handleHyperlinks(correctedString)
+    correctedString = findBoldOrItalicText(BOLD_TEXT, correctedString, FindType.BOLD)
+    correctedString = findBoldOrItalicText(ITALIC_TEXT, correctedString, FindType.ITALIC)
+    correctedString = findBoldOrItalicText(BACKTICKS_TEXT, correctedString, FindType.BACKTICKS)
+    return correctedString
+}
+
 private fun writeTableContentLine(writer: PrintWriter, line: String, numbOfSpaces: Double) {
     writer.write("\\hspace{${numbOfSpaces}cm}")
     val correctLine = line
@@ -158,10 +169,10 @@ private fun writeTableContentLine(writer: PrintWriter, line: String, numbOfSpace
             .replace("]", "")
             .replace("*", "")
             .replace(ANCHORS, "")
-            .replace("_", "\\_")
+            //.replace("_", "\\_")
             .replace("#", "\\#")
             .replace("&", "\\&")
-    writer.writeln("\\hyperref[sec:${correctLine.getFirstNumber()}]{$correctLine}")
+    writer.writeWithoutApostrophe("\\hyperref[sec:${correctLine.getFirstNumber()}]{$correctLine}")
 }
 
 /**
@@ -184,7 +195,7 @@ private fun handleHyperlinks(line: String): String {
             link = link.trim().drop(1).dropLast(1) // drop ( and )
             link = link.replace("\\#", "#")
             link = link.replace("\\&", "&")
-            link = link.replace("\\_", "_")
+            //link = link.replace("\\_", "_")
             // need to replace ` in hyperlink, because it breaks latex compilation
             text = text.replace("`", "")
             text = text.trim().drop(1).dropLast(1) // dropping [ and ]
@@ -206,14 +217,8 @@ private fun findBoldOrItalicText(regex: Regex,
             .toMutableList()
     allRegex.forEachIndexed { index, value ->
         when (type) {
-            FindType.BOLD -> allRegex[index] = "\\textbf{${value.replace("**", "")}}"
+            FindType.BOLD, FindType.BACKTICKS -> allRegex[index] = "\\textbf{${value.replace("**", "").replace("`", "")}}"
             FindType.ITALIC -> allRegex[index] = "\\textit{${value.replace("*", "")}}"
-            /*
-                replaces \_ with _. In default latex we needed to place \ before _.
-                But because of lstMakeShortInline[basicstyle=\ttfamily\bfseries]`
-                it isn't needed.
-             */
-            FindType.BACKTICKS -> allRegex[index] = value.replace("\\_", "_")
         }
     }
     var correctedLine = line.replace(regex, REGEX_PLACEHOLDER)

diff --git a/info/guide/diktat-coding-convention.md b/info/guide/diktat-coding-convention.md
@@ -30,7 +30,7 @@ I [Preface](#c0)
 * [2.4 Code comments](#c2.4)
     * [2.4.1 Add a blank line between the body of the comment and Kdoc tag-blocks](#r2.4.1)
     * [2.4.2 Do not comment on unused code blocks](#r2.4.2)
-    * [2.4.3 Do not comment on unused code blocks](#r2.4.3)
+    * [2.4.3 Code delivered to the client should not contain TODO/FIXME comments](#r2.4.3)
 
 [3. General formatting (typesetting)](#c3)
 * [3.1 File-related rules](#c3.1)
@@ -82,7 +82,8 @@ I [Preface](#c0)
 * [5.1 Function design](#c5.1)       
     * [5.1.1 Avoid functions that are too long ](#r5.1.1)
     * [5.1.2 Avoid deep nesting of function code blocks, limiting to four levels](#r5.1.2) 
-    * [5.1.3 Avoid using nested functions](#r5.1.3)        
+    * [5.1.3 Avoid using nested functions](#r5.1.3)
+    * [5.1.4 Negated function calls](#r5.1.4)        
 * [5.2 Function arguments](#c5.2)              
     * [5.2.1 The lambda parameter of the function should be placed at the end of the argument list](#r5.2.1)
     * [5.2.2 Number of function parameters should be limited to five](#r5.2.2) 
@@ -442,7 +443,7 @@ The basic format of KDoc is shown in the following example:
  * Other ...
  */
 fun method(arg: String) {
-    // …
+    // ...
 }
 ```
 
@@ -517,7 +518,7 @@ When the method has such details as arguments, return value, or can throw except
 /** 
  * This is the short overview comment for the example interface.
  *     / * Add a blank line between the comment text and each KDoc tag underneath * /
- * @since 2019-01-01
+ * @since 1.6
  */
  protected abstract class Sample {
     /**
@@ -559,8 +560,11 @@ Therefore, Kdoc should contain the following:
 Kdoc should not contain:
 - Empty descriptions in tag blocks. It is better not to write Kdoc than waste code line space.
 - There should be no empty lines between the method/class declaration and the end of Kdoc (`*/` symbols).
-Important note: KDoc does not support the `@deprecated` tag. Instead, use the `@Deprecated` annotation.
-
+- `@author` tag. It doesn't matter who originally created a class when you can use `git blame` or VCS of your choice to look through the changes history.
+Important notes:
+- KDoc does not support the `@deprecated` tag. Instead, use the `@Deprecated` annotation.
+- The `@since` tag should be used for versions only. Do not use dates in `@since` tag, it's confusing and less accurate.
+
 If a tag block cannot be described in one line, indent the content of the new line by *four spaces* from the `@` position to achieve alignment (`@` counts as one + three spaces).
 
 **Exception:**
@@ -595,20 +599,38 @@ Other KDoc tags (such as @param type parameters and @see.) can be added as follo
 ### <a name="c2.2"></a> 2.2 Adding comments on the file header
 
 This section describes the general rules of adding comments on the file header.
-Comments on the file header should be placed before the package name and imports. If you need to add more content to the comment, subsequently add it in the same format.
 
-Comments on the file header must include copyright information, without the creation date and author's name (use VCS for history management). Also, describe the content inside files that contain multiple or no classes.
+### <a name="r2.2.1"></a> 2.2.1 Formatting of comments in the file header
 
-Place comments on the file header before the package name and imports. If you need to add more content to the comment, subsequently add it in the same format.
+Comments on the file header should be placed before the package name and imports. If you need to add more content to the comment, subsequently add it in the same format.
+
+Comments on the file header must include copyright information, without the creation date and author's name (use VCS for history management).
+Also, describe the content inside files that contain multiple or no classes.
 
 The following examples for Huawei describe the format of the *copyright license*: \
 Chinese version: `版权所有 (c) 华为技术有限公司 2012-2020` \
 English version: `Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved.`
+`2012` and `2020` are the years the file was first created and the current year, respectively.
 
-Regarding the **release notes**, see examples below:
+Do not place **release notes** in header, use VCS to keep track of changes in file. Notable changes can be marked in individual KDocs using `@since` tag with version.
 
-- `2012-2020` can be modified according to your actual situation. `2012` and `2020` are the years the file was first created and last modified, respectively.
-These two years can be the same (for example, `2020–2020`). When the file is substantially changed (for example, through feature extensions and major refactorings), the subsequent years must be updated.
+Invalid example:
+```kotlin
+/**
+ * Release notes:
+ * 2019-10-11: added class Foo
+ */
+
+class Foo
+```
+
+Valid example:
+```kotlin
+/**
+ * @since 2.4.0
+ */
+class Foo
+```
 
 - The **copyright statement** can use your company's subsidiaries, as shown in the below examples: \
 Chinese version: `版权所有 (c) 海思半导体 2012-2020` \

diff --git a/info/guide/guide-TOC.md b/info/guide/guide-TOC.md
@@ -30,7 +30,7 @@ I [Preface](#c0)
 * [2.4 Code comments](#c2.4)
     * [2.4.1 Add a blank line between the body of the comment and Kdoc tag-blocks](#r2.4.1)
     * [2.4.2 Do not comment on unused code blocks](#r2.4.2)
-    * [2.4.3 Do not comment on unused code blocks](#r2.4.3)
+    * [2.4.3 Code delivered to the client should not contain TODO/FIXME comments](#r2.4.3)
 
 [3. General formatting (typesetting)](#c3)
 * [3.1 File-related rules](#c3.1)

diff --git a/info/guide/guide-chapter-2.md b/info/guide/guide-chapter-2.md
@@ -19,7 +19,7 @@ The basic format of KDoc is shown in the following example:
  * Other ...
  */
 fun method(arg: String) {
-    // …
+    // ...
 }
 ```
 

diff --git a/info/rules-mapping.md b/info/rules-mapping.md
@@ -37,11 +37,11 @@
 | KDOC_NO_NEWLINES_BETWEEN_BASIC_TAGS | [2.1.3](guide/diktat-coding-convention.md#r2.1.3) | yes |
 | KDOC_NO_NEWLINE_AFTER_SPECIAL_TAGS | [2.1.3](guide/diktat-coding-convention.md#r2.1.3) | yes |
 | KDOC_NO_DEPRECATED_TAG | [2.1.3](guide/diktat-coding-convention.md#r2.1.3) | yes |
+| KDOC_CONTAINS_DATE_OR_AUTHOR | [2.1.3](guide/diktat-coding-convention.md#r2.1.3) | no |
 | KDOC_NO_EMPTY_TAGS | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | no |
 | HEADER_WRONG_FORMAT | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | yes |
 | HEADER_MISSING_OR_WRONG_COPYRIGHT | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | yes |
 | WRONG_COPYRIGHT_YEAR | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | yes |
-| HEADER_CONTAINS_DATE_OR_AUTHOR | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | no |
 | HEADER_MISSING_IN_NON_SINGLE_CLASS_FILE | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | no |
 | HEADER_NOT_BEFORE_PACKAGE | [2.2.1](guide/diktat-coding-convention.md#r2.2.1) | yes |
 | KDOC_TRIVIAL_KDOC_ON_FUNCTION | [2.3.1](guide/diktat-coding-convention.md#r2.3.1) | no |
@@ -90,6 +90,7 @@
 | TOO_LONG_FUNCTION | [5.1.1](guide/diktat-coding-convention.md#r5.1.1) | no |
 | NESTED_BLOCK | [5.1.2](guide/diktat-coding-convention.md#r5.1.2) | no |
 | AVOID_NESTED_FUNCTIONS | [5.1.3](guide/diktat-coding-convention.md#r5.1.3) | yes |
+| INVERSE_FUNCTION_PREFERRED | [5.1.4](guide/diktat-coding-convention.md#r5.1.4) | yes |
 | LAMBDA_IS_NOT_LAST_PARAMETER | [5.2.1](guide/diktat-coding-convention.md#r5.2.1) | no |
 | TOO_MANY_PARAMETERS | [5.2.2](guide/diktat-coding-convention.md#r5.2.2) | no |
 | WRONG_OVERLOADING_FUNCTION_ARGUMENTS | [5.2.3](guide/diktat-coding-convention.md#r5.2.3) | no |

diff --git a/wp/README.md b/wp/README.md
@@ -0,0 +1,9 @@
+## White paper
+To generate a pdf document, you need to go to the `wp` folder and execute
+```
+make   
+```
+
+**Note**
+
+Minimum `MiKTeX` version - `20.11`
-Original file line number
+Diff line change
@@ Expand Up / @@ -19,7 +19,7 @@ The basic format of KDoc is shown in the following example: @@
      * Other ...
      */
     fun method(arg: String) {
-        // …
+        // ...
     }
     ```
@@ Expand Down @@