Merge pull request #11674 from BarkingBad/scaladoc/intrinsic-definitions

Add documentation for intrinsic types

Author: BarkingBad

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -784,6 +784,7 @@ object Build {
           ).mkString(File.pathSeparator),
         )
       },
+      Compile / doc / scalacOptions += "-Ydocument-synthetic-types",
       scalacOptions -= "-Xfatal-warnings",
       ivyConfigurations += SourceDeps.hide,
       transitiveClassifiers := Seq("sources"),
@@ -1638,7 +1639,8 @@ object Build {
               s"-source-links:" +
                 s"$stdLibRoot=github://scala/scala/v${stdlibVersion(Bootstrapped)}#src/library," +
                 s"docs=github://lampepfl/dotty/master#docs",
-              "-doc-root-content", docRootFile.toString
+              "-doc-root-content", docRootFile.toString,
+              "-Ydocument-synthetic-types"
             )
           ))
         }.evaluated,

project/Build.scala

@@ -42,7 +42,8 @@ object Scaladoc:
     socialLinks: List[SocialLinks] = Nil,
     identifiersToSkip: List[String] = Nil,
     regexesToSkip: List[String] = Nil,
-    rootDocPath: Option[String] = None
+    rootDocPath: Option[String] = None,
+    documentSyntheticTypes: Boolean = false,
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -171,7 +172,8 @@ object Scaladoc:
         socialLinksParsed,
         skipById.get ++ deprecatedSkipPackages.get,
         skipByRegex.get,
-        docRootContent.nonDefault
+        docRootContent.nonDefault,
+        YdocumentSyntheticTypes.get
       )
       (Some(docArgs), newContext)
     }

scaladoc/src/dotty/tools/scaladoc/Scaladoc.scala

@@ -57,5 +57,8 @@ class ScaladocSettings extends SettingGroup with CommonScalaSettings:
   val docRootContent: Setting[String] =
     StringSetting("-doc-root-content", "path", "The file from which the root package documentation should be imported.", "")
 
+  val YdocumentSyntheticTypes: Setting[Boolean] =
+    BooleanSetting("-Ydocument-synthetic-types", "Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib", false)
+
   def scaladocSpecificSettings: Set[Setting[_]] =
     Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent)

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

@@ -46,7 +46,7 @@ class DocRender(signatureRenderer: SignatureRenderer)(using DocContext):
           case 5 => h5(content)
           case 6 => h6(content)
     case Paragraph(text) => p(renderElement(text))
-    case Code(data: String) => code(raw(data)) // TODO add classes
+    case Code(data: String) => pre(code(raw(data))) // TODO add classes
     case HorizontalRule => hr
 
     case UnorderedList(items) => ul(listItems(items))

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

@@ -146,7 +146,7 @@ trait ClassLikeSupport:
         Some(parseMethod(c, dd.symbol))
 
       case td: TypeDef if !td.symbol.flags.is(Flags.Synthetic) && (!td.symbol.flags.is(Flags.Case) || !td.symbol.flags.is(Flags.Enum)) =>
-        Some(parseTypeDef(c, td))
+        Some(parseTypeDef(td))
 
       case vd: ValDef if !isSyntheticField(vd.symbol)
         && (!vd.symbol.flags.is(Flags.Case) || !vd.symbol.flags.is(Flags.Enum))
@@ -306,7 +306,7 @@ trait ClassLikeSupport:
 
     val enumTypes = companion.membersToDocument.collect {
       case td: TypeDef if !td.symbol.flags.is(Flags.Synthetic) && td.symbol.flags.is(Flags.Enum) && td.symbol.flags.is(Flags.Case) => td
-    }.toList.map(parseTypeDef(classDef, _))
+    }.toList.map(parseTypeDef)
 
     val enumNested = companion.membersToDocument.collect {
       case c: ClassDef if c.symbol.flags.is(Flags.Case) && c.symbol.flags.is(Flags.Enum) => processTree(c)(parseClasslike(c))
@@ -405,7 +405,7 @@ trait ClassLikeSupport:
       memberInfo.get(name).fold(argument.rhs.asSignature)(_.asSignature)
     )
 
-  def parseTypeDef(c: ClassDef, typeDef: TypeDef): Member =
+  def parseTypeDef(typeDef: TypeDef): Member =
     def isTreeAbstract(typ: Tree): Boolean = typ match {
       case TypeBoundsTree(_, _) => true
       case LambdaTypeTree(params, body) => isTreeAbstract(body)

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

@@ -160,12 +160,13 @@ class SymOps[Q <: Quotes](val q: Q) extends JavadocAnchorCreator with Scaladoc2A
           else if (sym.maybeOwner.isDefDef) Some(sym.owner)
           else None
 
-        val className = sym.className
+        val (className, anchor) = if sym.fullName == "scala.AnyRef" then // hacking relocation for synthetic `type AnyRef`
+          (Some("AnyRef"), None)
+        else
+          (sym.className, sym.anchor)
 
         val location = sym.packageNameSplitted ++ className
 
-        val anchor = sym.anchor
-
         val externalLink = {
             import q.reflect._
             import dotty.tools.dotc

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

@@ -116,6 +116,27 @@ case class ScaladocTastyInspector()(using ctx: DocContext) extends DocTastyInspe
         topLevels ++= parser.parseRootTree(treeRoot)
     }
 
+    val defn = ctx.compilerContext.definitions
+
+    if ctx.args.documentSyntheticTypes then
+      val intrinsicClassDefs = Seq(
+        defn.AnyClass,
+        defn.MatchableClass,
+        defn.AnyKindClass,
+        defn.AnyValClass,
+        defn.NullClass,
+        defn.NothingClass,
+        defn.SingletonClass,
+        defn.andType,
+        defn.orType,
+      ).map { s =>
+        "scala" -> s.asInstanceOf[parser.qctx.reflect.Symbol].tree.match {
+          case cd: parser.qctx.reflect.ClassDef => parser.parseClasslike(cd)
+          case td: parser.qctx.reflect.TypeDef  => parser.parseTypeDef(td)
+        }
+      }
+      topLevels ++= intrinsicClassDefs
+      topLevels += mergeAnyRefAliasAndObject(parser)
 
   def result(): (List[Member], Option[Comment]) =
     topLevels.clear()
@@ -134,6 +155,14 @@ case class ScaladocTastyInspector()(using ctx: DocContext) extends DocTastyInspe
       basePck.withMembers((basePck.members ++ rest).sortBy(_.name))
     }.toList -> rootDoc
 
+  def mergeAnyRefAliasAndObject(parser: TastyParser) =
+    val defn = ctx.compilerContext.definitions
+    val oM = parser.parseClasslike(defn.ObjectClass.asInstanceOf[parser.qctx.reflect.Symbol].tree.asInstanceOf[parser.qctx.reflect.ClassDef])
+    val aM = parser.parseTypeDef(defn.AnyRefAlias.asInstanceOf[parser.qctx.reflect.Symbol].tree.asInstanceOf[parser.qctx.reflect.TypeDef])
+    "scala" -> aM.copy(
+      kind = oM.kind,
+      members = oM.members
+    )
 /** Parses a single Tasty compilation unit. */
 case class TastyParser(
   qctx: Quotes,
@@ -154,13 +183,6 @@ case class TastyParser(
       report.warning(throwableToString(e), tree.pos)
       None
 
-  def processSymbol[T](sym: Symbol)(op: => T): Option[T] = try Option(op) catch
-    case t: Throwable =>
-      try report.warning(throwableToString(t), sym.tree.pos) catch
-        case _: Throwable =>
-          report.warning(s"Failed to process ${sym.fullName}:\n${throwableToString(t)}")
-      None
-
   def parseRootTree(root: Tree): Seq[(String, Member)] =
     val docs = Seq.newBuilder[(String, Member)]
     object Traverser extends TreeTraverser:
@@ -186,4 +208,3 @@ case class TastyParser(
       e.printStackTrace()
 
     docs.result()
-

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

@@ -83,7 +83,7 @@ object HTML:
   val ol = Tag("ol")
   val li = Tag("li")
   val code = Tag("code")
-
+  val pre = Tag("pre")
 
   val cls = Attr("class")
   val href = Attr("href")