final update

Author: seran

core/src/main/kotlin/org/evomaster/core/problem/api/param/Param.kt

@@ -9,16 +9,26 @@ abstract class Param(
         val genes : MutableList<Gene>
 ) : StructuralElement(genes){
 
+    /**
+     * Contains the description of the parameter.
+     */
+    var description: String? = null
+        set(value) {
+            if (!value.isNullOrEmpty() && field.isNullOrEmpty()) {
+                field = value
+            }
+        }
+
     //TODO need refactoring. eg shared abstract class for cases in which only 1 gene for sure
     @Deprecated("Assumes there is only 1 gene. Rather use primaryGene()")
      val gene : Gene = genes[0]
 
     /**
      * Return the most important gene defining this parameter.
-     * This is parameter type dependent.
+     * This is parameter-type-dependent.
      * Note that a parameter could have more than 1 gene.
      * For example, a body param could have a gene for the object, and one for its
-     * representation (eg, JSON vs XML)
+     * representation (e.g., JSON vs. XML)
      */
     open fun primaryGene() = genes[0]  //can be overridden if needed
 
@@ -34,6 +44,7 @@ abstract class Param(
         val copy = super.copy()
         if (copy !is Param)
             throw IllegalStateException("mismatched type: the type should be Param, but it is ${this::class.java.simpleName}")
+        copy.description = description
         return copy as Param
     }
 
@@ -43,4 +54,4 @@ abstract class Param(
     override fun copyContent(): Param {
         throw IllegalStateException("${this::class.java.simpleName}: copyContent() IS NOT IMPLEMENTED")
     }
-}
+}

core/src/main/kotlin/org/evomaster/core/problem/rest/builder/RestActionBuilderV3.kt

@@ -492,8 +492,10 @@ object RestActionBuilderV3 {
                         null
                     }
                 } ?: listOf()
+
             val action = RestCallAction(actionId, verb, restPath, params, produces = produces,
-                operationId = operation.operationId, links = links)
+                operationId = operation.operationId, links = links
+            )
 
             //TODO update for new parser
 //                        /*This section collects information regarding the types of data that are
@@ -591,6 +593,7 @@ object RestActionBuilderV3 {
                             messages: MutableList<String>
     ) {
         val name = p.name ?: "undefined"
+        val description = p.description
 
         if(p.schema == null){
             messages.add("No schema definition for parameter $name")
@@ -621,16 +624,14 @@ object RestActionBuilderV3 {
         }
 
         when (p.`in`) {
-
-            "query" -> {
-                params.add(QueryParam(name, gene, p.explode ?: true, p.style ?: Parameter.StyleEnum.FORM))
-            }
+            "query" -> params.add(QueryParam(name, gene, p.explode ?: true, p.style ?: Parameter.StyleEnum.FORM)
+                    .apply { this.description = description })
             /*
                 a path is inside a Disruptive Gene, because there are cases in which we want to prevent
                 mutation. Note that 1.0 means can always be mutated
              */
             "path" -> params.add(PathParam(name, CustomMutationRateGene("d_", gene, 1.0)))
-            "header" -> params.add(HeaderParam(name, gene))
+            "header" -> params.add(HeaderParam(name, gene).apply { this.description = description })
             "cookie" -> params // do nothing?
             //TODO "cookie" does it need any special treatment? as anyway handled in auth configs
             else -> throw IllegalStateException("Unrecognized: ${p.getIn()}")
@@ -706,6 +707,7 @@ object RestActionBuilderV3 {
         }
 
         val name = "body"
+        val description = operation.description ?: null
 
         val bodies = resolvedBody.content?.filter {
             /*
@@ -752,6 +754,8 @@ object RestActionBuilderV3 {
 
         val contentTypeGene = EnumGene<String>("contentType", bodies.keys)
         val bodyParam = BodyParam(gene, contentTypeGene)
+            .apply { this.description = description }
+
         val ns = bodyParam.notSupportedContentTypes
         if(ns.isNotEmpty()){
             messages.add("Not supported content types for body payload in $verb:$restPath : ${ns.joinToString()}")
@@ -810,17 +814,22 @@ object RestActionBuilderV3 {
         if (schema.enum?.isNotEmpty() == true) {
 
             when (type) {
-                "string" ->
+                "string" -> {
                     return EnumGene(name, (schema.enum.map {
                         if (it !is String)
-                            LoggingUtil.uniqueWarn(log, "an item of enum is not string (ie, ${it::class.java.simpleName}) for a property whose `type` is string and `name` is $name")
+                            LoggingUtil.uniqueWarn(
+                                log,
+                                "an item of enum is not string (ie, ${it::class.java.simpleName}) for a property whose `type` is string and `name` is $name"
+                            )
                         it.toString()
                     } as MutableList<String>).apply {
-                        if(options.invalidData) {
+                        if (options.invalidData) {
                             //Besides the defined values, add one to test robustness
                             add("EVOMASTER")
                         }
                     })
+                        .apply { this.description = schema.description }
+                }
                 /*
                     Looks like a possible bug in the parser, where numeric enums can be read as strings... got this
                     issue in GitLab schemas, eg for visibility_level
@@ -1509,6 +1518,8 @@ object RestActionBuilderV3 {
             else -> throw IllegalStateException("cannot create gene with constraints for gene:${geneClass.name}")
         }
 
+        mainGene.description = schema.description
+
         /*
             See:
             https://swagger.io/docs/specification/adding-examples/
@@ -1668,6 +1679,7 @@ object RestActionBuilderV3 {
             minLength = max(defaultMin, if (options.enableConstraintHandling) schema.minLength ?: 0 else 0),
             invalidChars = if(isInPath) listOf('/','.') else listOf()
         )
+            .apply { this.description = schema.description }
     }
 
     private fun createObjectFromReference(name: String,

core/src/main/kotlin/org/evomaster/core/search/gene/Gene.kt

@@ -50,7 +50,7 @@ import org.evomaster.core.search.service.monitor.ProcessMonitorExcludeField
 abstract class Gene(
         /**
          * The name for this gene, mainly needed for debugging.
-         * One actual use is for binding, e.g., paremeters in HTTP requests
+         * One actual use is for binding, e.g., parameters in HTTP requests
          */
         var name: String,
         /**
@@ -77,6 +77,17 @@ abstract class Gene(
         private val log: Logger = LoggerFactory.getLogger(Gene::class.java)
     }
 
+    /**
+     * Description about the gene.
+     */
+    var description: String? = null
+        set(value) {
+            if (!value.isNullOrEmpty() && field.isNullOrEmpty()) {
+                field = value
+            }
+        }
+
+
     /**
      * Whether this gene has been initialized, and can be used.
      * Note that gene can have validity constraints, and those might not be satisfied
@@ -93,7 +104,7 @@ abstract class Gene(
      * The type can be different, eg strings vs numbers, but still consistent.
      *
      * WARNING: genes are mutable, but here we check for references. this implies
-     * NO gene can overridde hashcode.
+     * NO gene can override hashcode.
      *
      * If A is bound to B, then as well B is bound to A.
      * If [this] is A, then binding genes will contain only B, and the binding genes of B
@@ -130,7 +141,6 @@ abstract class Gene(
             throw IllegalStateException("Trying to use a gene that is not initialized")
     }
 
-
     /**
      * Return all direct children of this gene.
      * Note that a gene can only have genes inside, and not other types of structural elements.
@@ -250,6 +260,7 @@ abstract class Gene(
         if (copy !is Gene)
             throw IllegalStateException("mismatched type: the type should be Gene, but it is ${this::class.java.simpleName}")
         copy.initialized = initialized
+        copy.description = description
         //this was incorrect, as subchildren might had different init state compared to this
         //copy.flatView().forEach{it.initialized = initialized}
         return copy
@@ -269,7 +280,7 @@ abstract class Gene(
                 a gene can refer to other genes outside of its tree.
                 when we make a copy we need to make sure that we refer to the new gene in the copied
                 individual, not the original individual.
-                so, this is applied only  when the root is an individual, otherswise skipped, because
+                so, this is applied only  when the root is an individual, otherwise skipped, because
                 would not be able to find those genes anyway
              */
             val postBinding = (original as Gene).bindingGenes.map { b ->
@@ -531,7 +542,7 @@ abstract class Gene(
      *   can be mutated, the choice is based with different strategies
      *
      *   @param randomness the source of non-determinism
-     *   @param apc adatpive parameter control singleton
+     *   @param apc adaptive parameter control singleton
      *   @param mwc mutation weight control
      *   @param interalGeneSelectionStrategy a strategy to select internal genes to mutate.
      *          In hypermutation, several genes could be mutated at same time.
@@ -1084,7 +1095,7 @@ abstract class Gene(
 
 
     /**
-     * here `valid` means that 1) [updateValue] performs correctly, ie, returns true AND 2) isLocallyValid is true
+     * here `valid` means that 1) [updateValue] performs correctly, i.e., returns true AND 2) isLocallyValid is true
      *
      * @param updateValue lambda performs update of value of the gene
      * @param undoIfUpdateFails represents whether it needs to undo the value update if [undoIfUpdateFails] returns false