MIgrate away from Kotlin Documentable

Scala3doc was only loosly using dokka model and it has started to blocking us.

This PR standarize over Member and expand semantic of Kind. This allow us to have more typesafe way to reason about code.

It will also make migration away from dokka easier if needed.

Author: romanowski

scala3doc-testcases/src/tests/extensionMethodSignatures.scala

@@ -17,6 +17,8 @@ class ClassOne
   extension (c: ClassTwo)
     def |||:(a: Int, b: Int, d: Int)(e: String): Int
       = 56
+    def ++:(a: Int): Int
+      = 45
 
   extension (b: Int)
     def secondGroup(): String

scala3doc-testcases/src/tests/givenSignatures.scala

@@ -2,43 +2,15 @@ package tests
 
 package givenSignatures
 
+object Obj
 
+given Seq[String] = Nil
 
-class GivenClass {
-    trait B
-    trait C[T]
-    val r: Int = 5
-    type R = Int
-    given R = r
-    trait Ord[T] {
-        def compare(x: T, y: T): Int
-        extension (x: T) def < (y: T) = compare(x, y) < 0
-        extension (x: T) def > (y: T) = compare(x, y) > 0
-    }
-    given intOrd: Ord[Int] with {
-        def compare(x: Int, y: Int) =
-            if (x < y) -1 else if (x > y) +1 else 0
-    }
+given GivenType = GivenType()
 
-    given asd(using int: Int): B with {}
+class GivenType
 
-    given asd2[T]: C[T] with {}
-
-    given listOrd[T](using ord: Ord[T]): Ord[List[T]] with {
-
-        def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match
-            case (Nil, Nil) => 0
-            case (Nil, _) => -1
-            case (_, Nil) => +1
-            case (x :: xs1, y :: ys1) =>
-                val fst = ord.compare(x, y)
-                if (fst != 0) fst else compare(xs1, ys1)
-    }
-
-    given IntOps: Int.type = Int
-
-    given GivenType = GivenType()
-
-    class GivenType
-}
+trait Ord[T]
 
+given listOrd[T](using ord: Ord[T]): Ord[List[T]]
+  = ???

scala3doc-testcases/src/tests/givenSignaturesPg.scala

@@ -0,0 +1,44 @@
+package tests
+
+package givenSignaturesPg
+
+
+
+class GivenClass {
+    trait B
+    trait C[T]
+    val r: Int = 5
+    type R = Int
+    given R = r
+    trait Ord[T] {
+        def compare(x: T, y: T): Int
+        extension (x: T) def < (y: T) = compare(x, y) < 0
+        extension (x: T) def > (y: T) = compare(x, y) > 0
+    }
+    given intOrd: Ord[Int] with {
+        def compare(x: Int, y: Int) =
+            if (x < y) -1 else if (x > y) +1 else 0
+    }
+
+    given asd(using int: Int): B with {}
+
+    given asd2[T]: C[T] with {}
+
+    given listOrd[T](using ord: Ord[T]): Ord[List[T]] with {
+
+        def compare(xs: List[T], ys: List[T]): Int = (xs, ys) match
+            case (Nil, Nil) => 0
+            case (Nil, _) => -1
+            case (_, Nil) => +1
+            case (x :: xs1, y :: ys1) =>
+                val fst = ord.compare(x, y)
+                if (fst != 0) fst else compare(xs1, ys1)
+    }
+
+    given IntOps: Int.type = Int
+
+    given GivenType = GivenType()
+
+    class GivenType
+}
+

scala3doc-testcases/src/tests/methodsAndConstructors.scala

@@ -47,3 +47,10 @@ class Methods:
 
  def arrays(a: Array[String], b: Array[Int]): Array[Double]
  = ???
+
+ def rightA1(a: Int): Int
+ = ???
+
+ def ++:(a: Int)(b: Double): Int
+ = ???
+

scala3doc-testcases/src/tests/modifiersSignatureTestSource.scala

@@ -24,6 +24,9 @@ abstract class Methods()
 
   implicit def toImplicitString(): String
    = "asd"
+
+  inline def method2(inline name: String): String
+  = "ala"
 }
 
 class ImplementedMethods() extends Methods/*<-*/()/*->*/

scala3doc/src/dotty/dokka/DocContext.scala

@@ -75,8 +75,8 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
     override def getOfflineMode: Boolean = false
     override def getFailOnWarning: Boolean = false
     override def getSourceSets: JList[DokkaSourceSet] = JList(mkSourceSet)
-    override def getModules: JList[DokkaConfiguration.DokkaModuleDescription] = JList()
-    override def getPluginsClasspath: JList[File] = JList()
+    override def getModules: JList[DokkaConfiguration.DokkaModuleDescription] = JNil
+    override def getPluginsClasspath: JList[File] = JNil
     override def getModuleName(): String = "ModuleName"
     override def getModuleVersion(): String = ""
 
@@ -94,13 +94,13 @@ case class DocContext(args: Scala3doc.Args, compilerContext: CompilerContext)
       )(using compilerContext))
 
     override def getPluginsConfiguration: JList[DokkaConfiguration.PluginConfiguration] =
-      JList()
+      JNil
 
     val mkSourceSet: DokkaSourceSet =
       new DokkaSourceSetImpl(
         /*displayName=*/ args.name,
         /*sourceSetID=*/ new DokkaSourceSetID(args.name, "main"),
-        /*classpath=*/ JList(),
+        /*classpath=*/ JNil,
         /*sourceRoots=*/ JSet(),
         /*dependentSourceSets=*/ JSet(),
         /*samples=*/ JSet(),

scala3doc/src/dotty/dokka/DottyDokkaPlugin.scala

@@ -120,8 +120,9 @@ class DottyDokkaPlugin extends DokkaJavaPlugin:
 
   val implicitMembersExtensionTransformer = extend(
     _.extensionPoint(CoreExtensions.INSTANCE.getDocumentableTransformer)
-      .fromRecipe(ImplicitMembersExtensionTransformer(_))
-      .name("implicitMembersExtensionTransformer")
+      .fromRecipe { case ctx @ given DokkaContext =>
+        new ImplicitMembersExtensionTransformer
+      }.name("implicitMembersExtensionTransformer")
   )
 
   val customDocumentationProvider = extend(

scala3doc/src/dotty/dokka/compat.scala

@@ -28,6 +28,12 @@ type JMap[K, V] = java.util.Map[K, V]
 type JHashMap[K, V] = java.util.HashMap[K, V]
 type JMapEntry[K, V] = java.util.Map.Entry[K, V]
 
+private val emptyListInst = JList()
+def JNil[A] = emptyListInst.asInstanceOf[JList[A]]
+
+private val emptyMapInst = JMap()
+def emptyJMap[A, B] = emptyMapInst.asInstanceOf[JMap[A, B]]
+
 type DRI = org.jetbrains.dokka.links.DRI
 val topLevelDri = org.jetbrains.dokka.links.DRI.Companion.getTopLevel
 

scala3doc/src/dotty/dokka/model/api/api.scala

@@ -53,20 +53,26 @@ trait ImplicitConversionProvider { def conversion: Option[ImplicitConversion] }
 trait Classlike
 
 enum Kind(val name: String){
-  case Class extends Kind("class") with Classlike
+  case Class(typeParams: Seq[TypeParameter], argsLists: Seq[Seq[Parameter]])
+    extends Kind("class") with Classlike
   case Object extends Kind("object") with Classlike
-  case Trait extends Kind("trait") with Classlike
+  case Trait(typeParams: Seq[TypeParameter], argsLists: Seq[Seq[Parameter]])
+    extends Kind("trait") with Classlike
   case Enum extends Kind("enum") with Classlike
-  case EnumCase extends Kind("case")
-  case Def extends Kind("def")
-  case Extension(on: ExtensionTarget) extends Kind("def")
-  case Constructor extends Kind("def")
+  case EnumCase(kind: Object.type | Type | Val.type) extends Kind("case")
+  case Def(typeParams: Seq[TypeParameter], argsLists: Seq[Seq[Parameter]])
+    extends Kind("def")
+  case Extension(on: ExtensionTarget, m: Kind.Def) extends Kind("def")
+  case Constructor(base: Kind.Def) extends Kind("def")
   case Var extends Kind("var")
   case Val extends Kind("val")
-  case Exported extends Kind("export")
-  case Type(concreate: Boolean, opaque: Boolean) extends Kind("Type") // should we handle opaque as modifier?
-  case Given(as: Option[Signature], conversion: Option[ImplicitConversion]) extends Kind("Given") with ImplicitConversionProvider
-  case Implicit(kind: Kind, conversion: Option[ImplicitConversion]) extends Kind(kind.name)  with ImplicitConversionProvider
+  case Exported(m: Kind.Def) extends Kind("export")
+  case Type(concreate: Boolean, opaque: Boolean, typeParams: Seq[TypeParameter])
+    extends Kind("Type") // should we handle opaque as modifier?
+  case Given(kind: Def | Class, as: Option[Signature], conversion: Option[ImplicitConversion])
+    extends Kind("Given") with ImplicitConversionProvider
+  case Implicit(kind: Kind.Def | Kind.Val.type, conversion: Option[ImplicitConversion])
+    extends Kind(kind.name)  with ImplicitConversionProvider
   case Unknown extends Kind("Unknown")
 }
 
@@ -91,6 +97,23 @@ object Annotation:
   case class LinkParameter(name: Option[String] = None, dri: DRI, value: String) extends AnnotationParameter
   case class UnresolvedParameter(name: Option[String] = None, unresolvedText: String) extends AnnotationParameter
 
+case class Parameter(
+  annotations: Seq[Annotation],
+  modifiers: String,
+  name: String,
+  dri: DRI,
+  signature: Signature,
+  isExtendedSymbol: Boolean = false,
+  isGrouped: Boolean = false
+)
+
+case class TypeParameter(
+  variance: "" | "+" | "-",
+  name: String,
+  dri: DRI,
+  signature: Signature
+)
+
 // TODO (longterm) properly represent signatures
 case class Link(name: String, dri: DRI)
 type Signature = Seq[String | Link]
@@ -114,7 +137,7 @@ object HierarchyGraph:
   def withEdges(edges: Seq[(LinkToType, LinkToType)]) = HierarchyGraph.empty ++ edges
 
 
-type Member = Documentable // with WithExtraProperty[_] // Kotlin does not add generics to ExtraProperty implemented by e.g. DFunction
+type Member = Documentable
 
 object Member:
   def unapply(d: Documentable): Option[(String, DRI, Visibility, Kind, Origin)] =
@@ -146,10 +169,12 @@ extension[T] (member: Member)
   def parents: Seq[LinkToType] = compositeMemberExt.fold(Nil)(_.parents)
   def directParents: Seq[Signature] = compositeMemberExt.fold(Nil)(_.directParents)
   def knownChildren: Seq[LinkToType] = compositeMemberExt.fold(Nil)(_.knownChildren)
+  def companion: Option[DRI] = compositeMemberExt.fold(None)(_.companion)
 
   def membersBy(op: Member => Boolean): Seq[Member] = allMembers.filter(op)
-  def membersByWithInheritancePartition(op: Member => Boolean): (Seq[Member], Seq[Member]) = membersBy(op).partition(_.inheritedFrom.isEmpty)
 
+extension (members: Seq[Member]) def byInheritance =
+  members.partition(_.inheritedFrom.isEmpty)
 
 extension (module: DModule)
   def driMap: Map[DRI, Member] = ModuleExtension.getFrom(module).fold(Map.empty)(_.driMap)

scala3doc/src/dotty/dokka/model/api/internalExtensions.scala

@@ -20,7 +20,7 @@ import collection.JavaConverters._
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.model.properties._
 
-private [model] case class MemberExtension(
+case class MemberExtension(
   visibility: Visibility,
   modifiers: Seq[dotty.dokka.model.api.Modifier],
   kind: Kind,
@@ -40,7 +40,8 @@ case class CompositeMemberExtension(
   members : Seq[Member] = Nil,
   directParents: Seq[Signature] = Nil,
   parents: Seq[LinkToType] = Nil,
-  knownChildren: Seq[LinkToType] = Nil
+  knownChildren: Seq[LinkToType] = Nil,
+  companion: Option[DRI] = None,
 ) extends ExtraProperty[Documentable]:
   override def getKey = CompositeMemberExtension