Fix missing JavaDoc in UtUtils class and update design doc (#1354)

Author: EgorkaKulikov

docs/UtUtilsClass.md

@@ -12,11 +12,13 @@ Previously UnitTestBot generated _utility methods_ for each test class when they
 
 For now UnitTestBot provides a special `UtUtils` class containing all _utility methods_ if at least one test class needs some of them. This class is generated once and the specific methods are imported from it if necessary. No need for _utility methods_ — no `UtUtils` class is generated.
 
+We create a separate `UtUtils` class for each supported codegen language (if this class is required).
+
 ## What does it look like
 
-Here is an example of a comment inherent to every `UtUtils` class:
+Here is an example of documentation comment inherent to every `UtUtils` class:
 
-<img width="494" alt="ututils" src="https://user-images.githubusercontent.com/64418523/196719780-2603f141-e922-40fc-9a0a-533aaacc5c49.png">
+![Documentation](images/utbot_ututils_2.0.png)
 
 As one can see, the comment mentions two characteristics of the `UtUtils` class:
 
@@ -39,7 +41,7 @@ rely on the proper methods from `UtUtils` class.
 
 ## Where to find it
 
-`UtUtils` class is usually located in the chosen **Test sources root** near the generated test classes.
+`UtUtils` class is usually located in the chosen **Test sources root** near the generated test classes. The corresponding package name mentions the language of the generated tests: e.g. `org.utbot.runtime.utils.java`.
 
 ## How to test
 

docs/images/utbot_ututils_2.0.png

@@ -124,6 +124,7 @@ open class CgClassFile(
 
 class CgClass(
     val id: ClassId,
+    val documentation: CgDocumentationComment?,
     val annotations: List<CgAnnotation>,
     val superclass: ClassId?,
     val interfaces: List<ClassId>,
@@ -149,7 +150,6 @@ class CgClass(
  */
 class CgClassBody(
     val classId: ClassId,
-    val documentation: CgDocumentationComment?,
     val methodRegions: List<CgMethodsCluster>,
     val staticDeclarationRegions: List<CgStaticsRegion>,
     val nestedClassRegions: List<CgNestedClassesRegion<*>>

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/domain/models/CgElement.kt

@@ -61,6 +61,8 @@ internal class CgJavaRenderer(context: CgRendererContext, printer: CgPrinter = C
         get() = this == context.generatedClass
 
     override fun visit(element: CgClass) {
+        element.documentation?.accept(this)
+
         for (annotation in element.annotations) {
             annotation.accept(this)
         }

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/model/CodeGenerator.kt

@@ -75,6 +75,8 @@ internal class CgKotlinRenderer(context: CgRendererContext, printer: CgPrinter =
         get() = (this == context.generatedClass) || isKotlinFile
 
     override fun visit(element: CgClass) {
+        element.documentation?.accept(this)
+
         for (annotation in element.annotations) {
             annotation.accept(this)
         }
@@ -115,8 +117,6 @@ internal class CgKotlinRenderer(context: CgRendererContext, printer: CgPrinter =
     }
 
     override fun visit(element: CgClassBody) {
-        element.documentation?.accept(this)
-
         // render regions for test methods
         for ((i, region) in (element.methodRegions + element.nestedClassRegions).withIndex()) {
             if (i != 0) println()

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/renderer/CgJavaRenderer.kt

@@ -49,25 +49,25 @@ fun buildClassFile(init: CgClassFileBuilder.() -> Unit) = CgClassFileBuilder().a
 
 class CgClassBuilder : CgBuilder<CgClass> {
     lateinit var id: ClassId
+    var documentation: CgDocumentationComment? = null
     val annotations: MutableList<CgAnnotation> = mutableListOf()
     var superclass: ClassId? = null
     val interfaces: MutableList<ClassId> = mutableListOf()
     var isStatic: Boolean = false
     var isNested: Boolean = false
     lateinit var body: CgClassBody
 
-    override fun build() = CgClass(id, annotations, superclass, interfaces, body, isStatic, isNested)
+    override fun build() = CgClass(id, documentation, annotations, superclass, interfaces, body, isStatic, isNested)
 }
 
 fun buildClass(init: CgClassBuilder.() -> Unit) = CgClassBuilder().apply(init).build()
 
 class CgClassBodyBuilder(val classId: ClassId) : CgBuilder<CgClassBody> {
-    var documentation: CgDocumentationComment? = null
     val methodRegions: MutableList<CgMethodsCluster> = mutableListOf()
     val staticDeclarationRegions: MutableList<CgStaticsRegion> = mutableListOf()
     val nestedClassRegions: MutableList<CgNestedClassesRegion<*>> = mutableListOf()
 
-    override fun build() = CgClassBody(classId, documentation, methodRegions, staticDeclarationRegions, nestedClassRegions)
+    override fun build() = CgClassBody(classId, methodRegions, staticDeclarationRegions, nestedClassRegions)
 }
 
 fun buildClassBody(classId: ClassId, init: CgClassBodyBuilder.() -> Unit) = CgClassBodyBuilder(classId).apply(init).build()

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/renderer/CgKotlinRenderer.kt

@@ -27,8 +27,8 @@ internal object CgUtilClassConstructor {
             // so they will be imported once IDEA reformatting action has worked
             declaredClass = buildClass {
                 id = utilsClassId
+                documentation = utilClassKind.utilClassDocumentation(codegenLanguage)
                 body = buildClassBody(utilsClassId) {
-                    documentation = utilClassKind.utilClassDocumentation(codegenLanguage)
                     staticDeclarationRegions += CgStaticsRegion("Util methods", utilMethodProvider.utilMethodIds.map { CgUtilMethod(it) })
                     nestedClassRegions += CgAuxiliaryNestedClassesRegion(
                         nestedClasses = listOf(

utbot-framework/src/main/kotlin/org/utbot/framework/codegen/tree/Builders.kt

@@ -35,7 +35,7 @@ sealed class UtilClassKind(
     fun utilClassDocumentation(codegenLanguage: CodegenLanguage): CgDocumentationComment
         = CgDocumentationComment(
         listOf(
-            CgDocRegularStmt(utilClassKindCommentText),
+            CgDocRegularStmt("$utilClassKindCommentText \n"),
             CgDocRegularStmt("$UTIL_CLASS_VERSION_COMMENT_PREFIX${utilClassVersion(codegenLanguage)}"),
         )
     )