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)}"),
  )
  )