handle @defines for doc gen

except enum

CHANGELOG.md

@@ -4,12 +4,15 @@
 
 - Advancing #312 "Reflect doc comments in generated code"
     - Most cases already covered, both for scala and java records/POJOs
-    - Note: `@define`s not yet addressed.
+    - Those include `@define`, except `#define enum`.
     - Comments used for annotations, i.e., starting with `@`, are not considered.
     - Also ignored are comments starting with `!`.
+    - Scala: For the root class, for which we don't have a general description, only
+      the params are generated. For simplicity in initial implementation, only first
+      non-empty comment line for each param is used.
     - Doc generation processing is always performed.
       (In retrospect, this should have been implemented long ago, but better late than never 😅)
-        - however, for now, `--no-doc` can be used to opt out of doc generation
+      - however, for now, `--no-doc` can be used to opt out of doc generation
 
 1.1.5
 

src/main/java/tscfg/example/JavaExampleCfg.java

@@ -1,4 +1,4 @@
-// generated by tscfg 1.2.0 on Tue Dec 17 21:46:38 PST 2024
+// generated by tscfg 1.2.1 on Wed Dec 18 22:40:37 PST 2024
 // source: src/main/tscfg/example/example.spec.conf
 
 package tscfg.example;
@@ -31,7 +31,7 @@ public static class Endpoint {
     public final java.lang.String path;
 
     /**
-     * an optional Integer with default value null
+     * an optional Integer with default value null (None is scala)
      */
     public final java.lang.Integer serial;
 

src/main/scala/tscfg/ModelBuilder.scala

@@ -80,8 +80,6 @@ class ModelBuilder(
 
         val comments        = childStruct.comments
         val optFromComments = comments.exists(_.trim.startsWith("@optional"))
-        val commentsOpt =
-          if (comments.isEmpty) None else Some(comments.mkString("\n"))
 
         // per Lightbend Config restrictions involving $, leave the key alone if
         // contains $, otherwise unquote the key in case is quoted.
@@ -113,7 +111,7 @@ class ModelBuilder(
           effDefault,
           childStruct.defineCaseOpt,
           docComments = childStruct.docComments,
-          commentsOpt,
+          comments = comments,
           parentClassMembers,
         )
 
@@ -169,7 +167,7 @@ class ModelBuilder(
       effDefault: Option[String],
       defineCase: Option[DefineCase],
       docComments: List[String],
-      commentsOpt: Option[String],
+      comments: List[String],
       parentClassMembers: Option[Map[String, model.AnnType]]
   ): AnnType = {
 
@@ -179,7 +177,7 @@ class ModelBuilder(
     // TODO review the following
     val updatedChildType = childType match {
       case objType: ObjectType =>
-        if (commentsOpt.exists(AnnType.isAbstract))
+        if (comments.exists(AnnType.isAbstract))
           AbstractObjectType(objType.members)
         else objType
 
@@ -195,7 +193,7 @@ class ModelBuilder(
       default = effDefault,
       defineCase = defineCase,
       docComments = docComments,
-      comments = commentsOpt,
+      comments = comments,
       parentClassMembers = parentClassMembers.map(_.toMap),
     )
   }

src/main/scala/tscfg/generators/TemplateGenerator.scala

@@ -25,10 +25,11 @@ class TemplateGenerator(opts: TemplateOpts) {
       .map { symbol =>
         val a = o.members(symbol)
 
+        // TODO simplify after having changed to List from Option for a.comments
         val (annotations, comments) = a.comments match {
-          case None => (List.empty, List.empty)
-          case Some(str) =>
-            val lines = str.split("\n").toList.filterNot(_.startsWith("!"))
+          case Nil => (List.empty, List.empty)
+          case comments =>
+            val lines = comments.filterNot(_.startsWith("!"))
             lines.partition(_.startsWith("@"))
         }
 

src/main/scala/tscfg/generators/docUtil.scala

@@ -1,25 +1,29 @@
 package tscfg.generators
 
-import tscfg.model.{AnnType, ObjectType}
+import tscfg.model.{AnnType, ObjectRealType}
 
 object docUtil {
 
   /** This is only for scala. For the root class, for which we don't have a
-    * description, only the params are generated (and, for simplicity at this
-    * time, only first non-empty comment line for each):
+    * general description, only the params are generated. For simplicity in
+    * initial implementation, only first non-empty comment line for each is
+    * used.
     */
   def getRootClassDoc(
-      objectType: ObjectType,
+      objectType: ObjectRealType,
       genOpts: GenOpts,
       symbol2id: String => String,
   ): String = {
     if (genOpts.genDoc) {
-      val docLines = objectType.members.toList.flatMap { case (symbol, a) =>
-        a.docComments.map(_.trim).filterNot(_.isEmpty).headOption map {
-          firstLine =>
-            List(s"@param ${symbol2id(symbol)}", s"  $firstLine")
+      val docLines = objectType.members.toList
+        .filterNot(_._2.isDefine)
+        .flatMap { case (symbol, a) =>
+          a.docComments.map(_.trim).filterNot(_.isEmpty).headOption map {
+            firstLine =>
+              List(s"@param ${symbol2id(symbol)}", s"  $firstLine")
+          }
         }
-      }.flatten
+        .flatten
       if (docLines.nonEmpty) {
         docLines.mkString(s"/** ", "\n  * ", "\n  */\n")
       }
@@ -40,7 +44,7 @@ object docUtil {
     else {
       val withParams = !onlyField && (genScala || genOpts.genRecords)
       a.t match {
-        case ot: ObjectType =>
+        case ot: ObjectRealType =>
           val paramDocs = if (withParams) {
             // only reflect params with comments
             ot.members.toList.flatMap { case (k, memberAnnType) =>

src/main/scala/tscfg/model.scala

@@ -16,9 +16,9 @@ object model {
       def :=(a: AnnType): (String, AnnType) = s -> a
 
       def %(a: AnnType): AnnType =
-        a.copy(comments = Some(s + a.comments.getOrElse("")))
+        a.copy(comments = List(s) ++ a.comments)
 
-      def %(t: Type): AnnType = AnnType(t, comments = Some(s))
+      def %(t: Type): AnnType = AnnType(t, comments = List(s))
     }
 
   }
@@ -88,7 +88,7 @@ object model {
       default: Option[String] = None,
       defineCase: Option[DefineCase] = None,
       docComments: List[String] = Nil,
-      comments: Option[String] = None,
+      comments: List[String] = Nil,
       parentClassMembers: Option[Map[String, model.AnnType]] = None,
   ) {
 
@@ -163,7 +163,7 @@ object model {
             val cmn =
               if (a.comments.isEmpty) ""
               else {
-                val lines = a.comments.get.split("\n")
+                val lines = a.comments
                 val noOptComments =
                   lines.filterNot(_.trim.startsWith("@optional"))
                 if (noOptComments.isEmpty) ""

src/main/tscfg/example/issue124a.spec.conf

@@ -1,9 +1,11 @@
+# Comment for Shared
 #@define
 Shared {
   c: string
   d: int
 }
 
+# Comment for example
 example {
   # @optional
   a: Shared

src/main/tscfg/example/issue64.spec.conf

@@ -1,3 +1,4 @@
+# Comment for (abstract) BaseModelConfig
 #@define abstract
 BaseModelConfig {
   uuids: [string]

src/test/java/tscfg/example/JavaIssue124aCfg.java

@@ -1,7 +1,15 @@
 package tscfg.example;
 
 public class JavaIssue124aCfg {
+
+  /**
+   * Comment for example
+   */
   public final JavaIssue124aCfg.Example example;
+
+  /**
+   * Comment for Shared
+   */
   public static class Shared {
     public final java.lang.String c;
     public final int d;
@@ -34,6 +42,10 @@ public Shared(com.typesafe.config.Config c, java.lang.String parentPath, $TsCfgV
 
   }
 
+
+  /**
+   * Comment for example
+   */
   public static class Example {
     public final Shared a;
     public final java.util.List<Shared> b;

src/test/java/tscfg/example/JavaIssue64Cfg.java

@@ -2,6 +2,10 @@
 
 public class JavaIssue64Cfg {
   public final JavaIssue64Cfg.Test test;
+
+  /**
+   * Comment for (abstract) BaseModelConfig
+   */
   public abstract static class BaseModelConfig {
     public final double scaling;
     public final java.util.List<java.lang.String> uuids;

src/test/scala/tscfg/ModelBuilderSpec.scala

@@ -40,7 +40,7 @@ class ModelBuilderSpec extends AnyWordSpec {
       t: Type,
       optional: Boolean = false,
       default: Option[String] = None,
-      comments: Option[String] = None
+      comments: List[String] = Nil
   ): Unit = {
     val at = objType.members(memberName)
     assert(at.t === t)

src/test/scala/tscfg/example/ScalaIssue124aCfg.scala

@@ -1,9 +1,15 @@
 package tscfg.example
 
+/** @param example
+  *   Comment for example
+  */
 final case class ScalaIssue124aCfg(
   example : ScalaIssue124aCfg.Example
 )
 object ScalaIssue124aCfg {
+
+  /** Comment for Shared
+    */
   final case class Shared(
     c : java.lang.String,
     d : scala.Int
@@ -37,6 +43,9 @@ object ScalaIssue124aCfg {
 
   }
 
+
+  /** Comment for example
+    */
   final case class Example(
     a : scala.Option[ScalaIssue124aCfg.Shared],
     b : scala.Option[scala.List[ScalaIssue124aCfg.Shared]]

src/test/scala/tscfg/example/ScalaIssue64Cfg.scala

@@ -4,6 +4,9 @@ final case class ScalaIssue64Cfg(
   test            : ScalaIssue64Cfg.Test
 )
 object ScalaIssue64Cfg {
+
+  /** Comment for (abstract) BaseModelConfig
+    */
   sealed abstract class BaseModelConfig (
    val scaling : scala.Double,
     val uuids   : scala.List[java.lang.String]