UX improvements for scaladoc

Author: BarkingBad

scaladoc-testcases/src/tests/listindocstring.scala

@@ -1,6 +1,9 @@
+package tests
+package listindocstring
+
 /**
  * These are useful methods that exist for both $some and $none.
- *  * [[isDefined]] — True if not empty
+ *  - [[isDefined]] — True if not empty
  *  - [[isEmpty]] — True if empty
  *  - [[nonEmpty]] — True if not empty
  *  - [[orElse]] — Evaluate and return alternate optional value if empty

scaladoc-testcases/src/tests/secondaryconstructor.scala

@@ -0,0 +1,7 @@
+package tests
+package secondaryconstructors
+
+class Person(val firstName: String, val lastName: String, val age: Int):
+  def this(firstName: String) = this(firstName, "", 0)
+  def this(firstName: String, lastName: String) = this(firstName, lastName, 0)
+

scaladoc-testcases/src/tests/traitmethodsgrouping.scala

@@ -0,0 +1,6 @@
+package tests
+package traitmethodsgrouping
+
+trait Promise:
+  def shouldBeAbstract: Int
+  def shouldBeConcrete: Int = 1

scaladoc/src/dotty/tools/scaladoc/SourceLinks.scala

@@ -122,7 +122,7 @@ case class SourceLinks(links: Seq[SourceLink], projectRoot: Path):
     else resolveRelativePath(rawPath)
 
   def pathTo(member: Member): Option[String] =
-    member.sources.flatMap(s => pathTo(Paths.get(s.path), member.name, Option(s.lineNumber).map(_ + 1)))
+    member.sources.flatMap(s => pathTo(s.path, member.name, Option(s.lineNumber).map(_ + 1)))
 
 object SourceLinks:
 

scaladoc/src/dotty/tools/scaladoc/api.scala

@@ -146,7 +146,7 @@ case class Member(
   modifiers: Seq[Modifier] = Nil,
   annotations: List[Annotation] = Nil,
   signature: Signature = Signature(),
-  sources: Option[TastyDocumentableSource] = None,
+  sources: Option[TastyMemberSource] = None,
   origin: Origin = Origin.RegularlyDefined,
   inheritedFrom: Option[InheritedFrom] = None,
   graph: HierarchyGraph = HierarchyGraph.empty,
@@ -231,4 +231,4 @@ extension (s: Signature)
       case l: Link => l.name
     }.mkString
 
-case class TastyDocumentableSource(val path: String, val lineNumber: Int)
+case class TastyMemberSource(val path: java.nio.file.Path, val lineNumber: Int)

scaladoc/src/dotty/tools/scaladoc/renderers/MemberRenderer.scala

@@ -68,7 +68,7 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
 
   def source(m: Member): Seq[AppliedTag] =
     summon[DocContext].sourceLinks.pathTo(m).fold(Nil){ link =>
-      tableRow("Source", a(href := link)("(source)"))
+      tableRow("Source", a(href := link)(m.sources.fold("(source)")(_.path.getFileName().toString())))
     }
 
   def deprecation(m: Member): Seq[AppliedTag] = m.deprecated.fold(Nil){ a =>
@@ -202,22 +202,34 @@ class MemberRenderer(signatureRenderer: SignatureRenderer)(using DocContext) ext
     case m: Member => m.inheritedFrom.nonEmpty
     case g: MGroup => g.members.exists(isInherited)
 
+  private def isAbstract(m: Member | MGroup): Boolean = m match
+    case m: Member => m.modifiers.contains(Modifier.Abstract)
+    case g: MGroup => g.members.exists(isAbstract)
+
   private type SubGroup = (String, Seq[Member | MGroup])
   private def buildGroup(name: String, subgroups: Seq[SubGroup]): Tab =
     val all = subgroups.map { case (name, members) =>
       val (allInherited, allDefined) = members.partition(isInherited)
       val (depDefined, defined) = allDefined.partition(isDeprecated)
       val (depInherited, inherited) = allInherited.partition(isDeprecated)
-      (
-        actualGroup(name, defined),
-        actualGroup(s"Deprecated ${name.toLowerCase}", depDefined),
-        actualGroup(s"Inherited ${name.toLowerCase}", inherited),
-        actualGroup(s"Deprecated and Inherited ${name.toLowerCase}", depInherited)
+      val normalizedName = name.toLowerCase
+      val definedWithGroup = if Set("methods", "fields").contains(normalizedName) then
+          val (abstr, concr) = defined.partition(isAbstract)
+          Seq(
+            actualGroup(s"Abstract ${normalizedName}", abstr),
+            actualGroup(s"Concrete ${normalizedName}", concr)
+          )
+        else
+          Seq(actualGroup(name, defined))
+
+      definedWithGroup ++ List(
+        actualGroup(s"Deprecated ${normalizedName}", depDefined),
+        actualGroup(s"Inherited ${normalizedName}", inherited),
+        actualGroup(s"Deprecated and Inherited ${normalizedName}", depInherited)
       )
     }
 
-    val children =
-      all.flatMap(_._1) ++ all.flatMap(_._2) ++ all.flatMap(_._3) ++ all.flatMap(_._4)
+    val children = all.flatten.flatten
     if children.isEmpty then emptyTab
     else Tab(name, name, h2(tabAttr(name))(name) +: children, "selected")
 

scaladoc/src/dotty/tools/scaladoc/tasty/BasicSupport.scala

@@ -36,8 +36,8 @@ trait BasicSupport:
     def documentation = sym.docstring.map(parseComment(_, sym.tree))
 
     def source(using Quotes) =
-      val path = sym.pos.map(_.sourceFile.jpath).filter(_ != null).map(_.toAbsolutePath).map(_.toString)
-      path.map(TastyDocumentableSource(_, sym.pos.get.startLine))
+      val path = sym.pos.map(_.sourceFile.jpath).filter(_ != null).map(_.toAbsolutePath)
+      path.map(TastyMemberSource(_, sym.pos.get.startLine))
 
     def getAnnotations(): List[Annotation] =
       sym.annotations.filterNot(_.symbol.packageName.startsWith("scala.annotation.internal")).map(parseAnnotation).reverse

scaladoc/src/dotty/tools/scaladoc/tasty/comments/MarkdownParser.scala

@@ -36,7 +36,7 @@ object MarkdownParser {
     ) ++ additionalExtensions
 
     new MutableDataSet()
-      .setFrom(ParserEmulationProfile.KRAMDOWN.getOptions)
+      .setFrom(ParserEmulationProfile.COMMONMARK.getOptions)
       .set(Parser.EXTENSIONS, Arrays.asList(extArray:_*))
       .set(EmojiExtension.ROOT_IMAGE_PATH,
         "https://github.global.ssl.fastly.net/images/icons/emoji/")