WIP

Author: romanowski

scala3doc/resources/dotty_res/scripts/ux.js

@@ -5,6 +5,16 @@ window.addEventListener("DOMContentLoaded", () => {
       document.getElementById("leftColumn").classList.toggle("open");
     };
   }
+
+  var elements = document.getElementsByClassName("documentableElement")
+  if (elements) {
+    for (i = 0; i < elements.length; i++) {
+      elements[i].onclick = function(){
+        this.classList.toggle("expand")
+      }
+    }
+  }
+
   var logo = document.getElementById("logo");
   if (logo) {
     logo.onclick = function() {

scala3doc/resources/dotty_res/styles/scalastyle.css

@@ -12,6 +12,9 @@
   --inactive-fg: #777;
   --title-fg: #00485E;
 
+  --link-sig-fd: #7c99a5;
+  --link-sig-hover-fd: #7c99a5;
+
   --leftbar-bg: #003048;
   --leftbar-fg: #fff;
   --leftbar-current-bg: #0090BB;
@@ -364,7 +367,7 @@ dl.attributes > dt.implicit {
 }
 dl.attributes > dd {
   display: block;
-  padding-left: 10em;
+  padding-left: 5em;
   margin-bottom: 5px;
   min-height: 15px;
 }
@@ -437,11 +440,43 @@ footer .pull-right {
   margin-left: auto;
 }
 
+
 .modifiers {
-  width: 12em;
   display: table-cell;
-  text-align: right;
   padding-right: 0.5em;
+  min-width: 10em;
+  max-width: 10em;
+  overflow: hidden;
+  direction: rtl;
+  white-space: nowrap;
+  text-indent: 0em;
+}
+
+.modifiers .other-modifiers {
+  color: gray;
+}
+
+.other-modifiers a, .other-modifiers a:visited, .other-modifiers span[data-unresolved-link] {
+  color: var(--link-sig-fd);
+}
+
+.expand .modifiers {
+  display: inline-table;
+  min-width: 4em;
+}
+
+.signature {
+  color: gray;
+  display: table-cell;
+  padding-left: 0.5em;
+}
+
+.signature a, .signature a:visited, .signature span[data-unresolved-link] {
+  color: var(--link-sig-fd);
+}
+
+.expand .signature {
+  display: inline;
 }
 
 .documentableElement {
@@ -454,15 +489,50 @@ footer .pull-right {
   font-weight: 500;
   font-size: 12px;
   background: var(--code-bg);
+  border: 0.25em solid white;
 }
 
 .documentableElement>div {
   display: table;
 }
 
+.expand.documentableElement>div {
+  display: block;
+  padding-left: 3em;
+}
+
+.expand.documentableElement>div.header {
+  display: block;
+  padding-left: 7.5em;
+  text-indent: -4.5em;
+}
+
+.documentableElement>div .cover {
+  display: none;
+}
+
+.documentableElement.expand>div .cover {
+  display: block;
+}
+
+.expand .doc {
+  margin-left: 6.5em;
+}
+
+.documentableElement:hover {
+  cursor: pointer;
+  border-left: 0.25em solid var(--leftbar-bg);
+}
+
 .annotations {
-  margin-left: 9em;
+  color: gray;
+  display: none;
 }
+
+.expand .annotations {
+  display: inline-block;
+}
+
 .documentableAnchor {
   position: absolute;
   width: 24px;

scala3doc/src/dotty/dokka/SourceLinks.scala

@@ -6,7 +6,30 @@ import liqp.Template
 import dotty.dokka.model.api._
 import dotty.tools.dotc.core.Contexts.Context
 
-case class SourceLink(val path: Option[Path], val urlTemplate: Template)
+trait SourceLink:
+  val path: Option[Path] = None
+  def render(path: String, operation: String, line: Option[Int]): String
+
+case class PrefixedSourceLink(val myPath: Path, nested: SourceLink) extends SourceLink:
+  export nested.render
+  override val path = Some(myPath)
+
+case class TemplateSourceLink(val urlTemplate: Template) extends SourceLink:
+  override val path: Option[Path] = None
+  override def render(path: String, operation: String, line: Option[Int]): String =
+    val config = java.util.HashMap[String, Object]()
+    config.put("path", path)
+    line.foreach(l => config.put("line", l.toString))
+    config.put("operation", operation)
+
+    urlTemplate.render(config)
+
+case class WebBasedSourceLink(prefix: String, revision: String) extends SourceLink:
+  override val path: Option[Path] = None
+  override def render(path: String, operation: String, line: Option[Int]): String =
+    val action = if operation == "view" then "blob" else operation
+    val linePart = line.fold("")(l => s"#L$l")
+    s"$prefix/$action/$revision/$path$linePart"
 
 object SourceLink:
   val SubPath = "([^=]+)=(.+)".r
@@ -18,41 +41,39 @@ object SourceLink:
     "€{FILE_LINE}" -> "{{ line }}"
   )
 
-  def githubTemplate(organization: String, repo: String)(revision: String) =
-    s"""https://github.com/$organization/$repo/{{ operation | replace: "view", "blob" }}/$revision/{{ path }}#L{{ line }}""".stripMargin
+  def githubPrefix(org: String, repo: String) = s"https://github.com/$org/$repo"
 
-  def gitlabTemplate(organization: String, repo: String)(revision: String) =
-    s"""https://gitlab.com/$organization/$repo/-/{{ operation | replace: "view", "blob" }}/$revision/{{ path }}#L{{ line }}"""
+  def gitlabPrefix(org: String, repo: String) = s"https://gitlab.com/$org/$repo/-"
 
 
   private def parseLinkDefinition(s: String): Option[SourceLink] = ???
 
   def parse(string: String, revision: Option[String]): Either[String, SourceLink] =
     def asTemplate(template: String) =
-       try Right(SourceLink(None,Template.parse(template))) catch
+       try Right(TemplateSourceLink(Template.parse(template))) catch
             case e: RuntimeException =>
               Left(s"Failed to parse template: ${e.getMessage}")
 
     string match
       case KnownProvider(name, organization, repo) =>
-        def withRevision(template: String => String) =
-            revision.fold(Left(s"No revision provided"))(rev => Right(SourceLink(None, Template.parse(template(rev)))))
+        def withRevision(template: String => SourceLink) =
+          revision.fold(Left(s"No revision provided"))(r => Right(template(r)))
 
         name match
           case "github" =>
-            withRevision(githubTemplate(organization, repo))
+            withRevision(rev => WebBasedSourceLink(githubPrefix(organization, repo), rev))
           case "gitlab" =>
-            withRevision(gitlabTemplate(organization, repo))
+            withRevision(rev => WebBasedSourceLink(gitlabPrefix(organization, repo), rev))
           case other =>
             Left(s"'$other' is not a known provider, please provide full source path template.")
 
       case SubPath(prefix, config) =>
         parse(config, revision) match
           case l: Left[String, _] => l
-          case Right(SourceLink(Some(prefix), _)) =>
+          case Right(_:PrefixedSourceLink) =>
             Left(s"Source path $string has duplicated subpath setting (scm template can not contains '=')")
-          case Right(SourceLink(None, template)) =>
-            Right(SourceLink(Some(Paths.get(prefix)), template))
+          case Right(nested) =>
+            Right(PrefixedSourceLink(Paths.get(prefix), nested))
       case BrokenKnownProvider("gitlab" | "github") =>
         Left(s"Does not match known provider syntax: `<name>://organization/repository`")
       case scaladocSetting if ScalaDocPatten.findFirstIn(scaladocSetting).nonEmpty =>
@@ -70,15 +91,9 @@ type Operation = "view" | "edit"
 case class SourceLinks(links: Seq[SourceLink], projectRoot: Path):
   def pathTo(rawPath: Path, line: Option[Int] = None, operation: Operation = "view"): Option[String] =
     def resolveRelativePath(path: Path) =
-      links.find(_.path.forall(p => path.startsWith(p))).map { link =>
-        val config = java.util.HashMap[String, Object]()
-        val pathString = path.toString.replace('\\', '/')
-        config.put("path", pathString)
-        line.foreach(l => config.put("line", l.toString))
-        config.put("operation", operation)
-
-        link.urlTemplate.render(config)
-      }
+      links
+        .find(_.path.forall(p => path.startsWith(p)))
+        .map(_.render(path.toString.replace('\\', '/'), operation, line))
 
     if rawPath.isAbsolute then
       if rawPath.startsWith(projectRoot) then resolveRelativePath(projectRoot.relativize(rawPath))

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

@@ -8,6 +8,7 @@ import collection.JavaConverters._
 import org.jetbrains.dokka.model.doc._
 import org.jetbrains.dokka.model.properties._
 import org.jetbrains.dokka.pages._
+import dotty.dokka.tasty.comments.Comment
 
 enum Visibility(val name: String):
   case Unrestricted extends Visibility("")
@@ -156,6 +157,7 @@ extension[T] (member: Member):
   def origin: Origin =  memberExt.fold(Origin.DefinedWithin)(_.origin)
   def annotations: List[Annotation] = memberExt.fold(Nil)(_.annotations)
   def sources: Option[TastyDocumentableSource] = memberExt.fold(None)(_.sources)
+  def docs: Option[Comment] = memberExt.fold(None)(_.rawDoc)
   def name = member.getName
   def dri = member.getDri
 
@@ -173,3 +175,5 @@ extension (module: DModule):
   def driMap: Map[DRI, Member] = ModuleExtension.getFrom(module).fold(Map.empty)(_.driMap)
 
 case class TastyDocumentableSource(val path: String, val lineNumber: Int)
+
+type DocPart = DocTag

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

@@ -19,6 +19,7 @@ import org.jetbrains.dokka.model.DModule
 import collection.JavaConverters._
 import org.jetbrains.dokka.model.doc.DocumentationNode
 import org.jetbrains.dokka.model.properties._
+import dotty.dokka.tasty.comments.Comment
 
 case class MemberExtension(
   visibility: Visibility,
@@ -29,6 +30,7 @@ case class MemberExtension(
   sources: Option[TastyDocumentableSource] = None,
   origin: Origin = Origin.DefinedWithin,
   graph: HierarchyGraph = HierarchyGraph.empty,
+  rawDoc: Option[Comment] = None
 ) extends ExtraProperty[Documentable]:
  override def getKey = MemberExtension
 

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

@@ -8,6 +8,7 @@ import org.jetbrains.dokka.model.properties._
 import org.jetbrains.dokka.pages._
 import dotty.dokka.model.api.Signature
 import dotty.dokka.model.api.HierarchyGraph
+import dotty.dokka.model.api.Member
 
 enum TableStyle extends org.jetbrains.dokka.pages.Style:
   case Borderless
@@ -30,15 +31,15 @@ case class HtmlContentNode(
   override def getExtra = extra
   override def withNewExtras(p: PropertyContainer[ContentNode]) = copy(extra = p)
 
-class ScalaTagWrapper(root: DocTag) extends TagWrapper(null):
+class ScalaTagWrapper(root: DocTag, val name: String) extends TagWrapper(null):
   override def getRoot = root
 
 object ScalaTagWrapper {
 
-  case class See(root: DocTag) extends ScalaTagWrapper(root)
-  case class Todo(root: DocTag) extends ScalaTagWrapper(root)
-  case class Note(root: DocTag) extends ScalaTagWrapper(root)
-  case class Example(root: DocTag) extends ScalaTagWrapper(root)
+  case class See(root: DocTag) extends ScalaTagWrapper(root, "See")
+  case class Todo(root: DocTag) extends ScalaTagWrapper(root, "Todo")
+  case class Note(root: DocTag) extends ScalaTagWrapper(root, "Note")
+  case class Example(root: DocTag) extends ScalaTagWrapper(root, "Example")
   case class NestedNamedTag(
     name: String,
     subname: String,
@@ -101,7 +102,8 @@ case class DocumentableElement(
   brief: Seq[ContentNode],
   originInfo: Signature,
   attributes: Map[String, String],
-  params: ContentNodeParams
+  params: ContentNodeParams,
+  member: Member
 ) extends ScalaContentNode(params):
   override def newInstance(params: ContentNodeParams) = copy(params = params)
 
@@ -125,3 +127,7 @@ case class DocumentableList(
 
 case class DocumentableFilter(params: ContentNodeParams) extends ScalaContentNode(params):
   override def newInstance(params: ContentNodeParams) = copy(params = params)
+
+case class MemberInfo(member: Member, params: ContentNodeParams)
+  extends ScalaContentNode(params):
+    override def newInstance(params: ContentNodeParams) = copy(params = params)

scala3doc/src/dotty/dokka/tasty/BasicSupport.scala

@@ -41,6 +41,8 @@ trait BasicSupport:
       case None =>
           Map.empty
 
+    def documentation2 = sym.docstring.map(preparseComment(_, sym.tree))
+
     def source =
       val path = Some(sym.pos.get.sourceFile.jpath).filter(_ != null).map(_.toAbsolutePath).map(_.toString)
       path.map(TastyDocumentableSource(_, sym.pos.get.startLine))

scala3doc/src/dotty/dokka/tasty/ClassLikeSupport.scala

@@ -442,10 +442,10 @@ trait ClassLikeSupport:
         null,
         JNil,
         emptyJMap,
-        symbol.documentation.asJava,
+        emptyJMap,
         null,
         placeholderModifier,
         ctx.sourceSet.toSet,
         /*isExpectActual =*/ false,
-        PropertyContainer.Companion.empty().plus(member).plus(compositeExt)
+        PropertyContainer.Companion.empty().plus(member.copy(rawDoc = symbol.documentation2)).plus(compositeExt)
     )

scala3doc/src/dotty/dokka/tasty/ScalaDocSupport.scala

@@ -7,10 +7,50 @@ import org.jetbrains.dokka.model.{doc => dkkd}
 import dotty.dokka.Scala3doc.CommentSyntax
 import dotty.dokka.ScalaTagWrapper
 import comments.{kt, dkk}
+import dotty.dokka.tasty.comments.Comment
 
 trait ScaladocSupport { self: TastyParser =>
   import qctx.reflect._
 
+  def preparseComment(
+    docstring: String,
+    tree: Tree
+  ): Comment =
+    val commentString: String =
+      if tree.symbol.isClassDef || tree.symbol.owner.isClassDef then
+        import dotty.tools.dotc
+        given ctx: dotc.core.Contexts.Context = qctx.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
+
+        val sym = tree.symbol.asInstanceOf[dotc.core.Symbols.Symbol]
+
+        comments.CommentExpander.cookComment(sym)(using ctx)
+          .get.expanded.get
+      else
+        docstring
+
+    val preparsed =
+      comments.Preparser.preparse(comments.Cleaner.clean(commentString))
+
+    val commentSyntax =
+      preparsed.syntax.headOption match {
+        case Some(commentSetting) =>
+          CommentSyntax.parse(commentSetting).getOrElse {
+            val msg = s"not a valid comment syntax: $commentSetting, defaulting to Markdown syntax."
+            // we should update pos with span from documentation
+            report.warning(msg, tree.pos)
+            CommentSyntax.default
+          }
+        case None => ctx.args.defaultSyntax
+      }
+
+    val parser = commentSyntax match {
+      case CommentSyntax.Wiki =>
+        comments.WikiCommentParser(comments.Repr(qctx)(tree.symbol))
+      case CommentSyntax.Markdown =>
+        comments.MarkdownCommentParser(comments.Repr(qctx)(tree.symbol))
+    }
+    parser.parse(preparsed)
+
   def parseComment(
     docstring: String,
     tree: Tree