Automate publishing docs with intrincis types for stdlib

Author: BarkingBad

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

@@ -790,6 +790,7 @@ object Build {
           ).mkString(File.pathSeparator),
         )
       },
+      Compile / doc / scalacOptions += "-Ydocument-synthetic-types",
       scalacOptions -= "-Xfatal-warnings",
       ivyConfigurations += SourceDeps.hide,
       transitiveClassifiers := Seq("sources"),
@@ -1640,7 +1641,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,

compiler/src/dotty/tools/dotc/core/Definitions.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)
     }

project/Build.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 in stdlib", true)
+
   def scaladocSpecificSettings: Set[Setting[_]] =
     Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent)

scaladoc/src/dotty/tools/scaladoc/Scaladoc.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/ScaladocSettings.scala

@@ -83,14 +83,10 @@ trait SyntheticsSupport:
     import dotty.tools.dotc
     given dotc.core.Contexts.Context = qctx.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
     val classdef = rdef.asInstanceOf[dotc.ast.tpd.TypeDef]
-    classdef.symbol.info match
-      case ci: dotc.core.Types.ClassInfo =>
-        val ref = ci.appliedRef
-        val baseTypes: List[(dotc.core.Symbols.Symbol, dotc.core.Types.Type)] =
-          ref.baseClasses.map(b => b -> ref.baseType(b))
-        baseTypes.asInstanceOf[List[(Symbol, TypeRepr)]]
-      case _ =>
-        List.empty
+    val ref = classdef.symbol.info.asInstanceOf[dotc.core.Types.ClassInfo].appliedRef
+    val baseTypes: List[(dotc.core.Symbols.Symbol, dotc.core.Types.Type)] =
+      ref.baseClasses.map(b => b -> ref.baseType(b))
+    baseTypes.asInstanceOf[List[(Symbol, TypeRepr)]]
   }
 
   def hackExists(using Quotes)(rpos: qctx.reflect.Position) = {
@@ -102,9 +98,7 @@ trait SyntheticsSupport:
     pos.exists
   }
 
-  def getSupertypes(using Quotes)(c: ClassDef) = hackGetSupertypes(c) match
-    case _ :: tail => tail
-    case _ => List.empty
+  def getSupertypes(using Quotes)(c: ClassDef) = hackGetSupertypes(c).tail
 
   def typeForClass(c: ClassDef): TypeRepr =
     import qctx.reflect._

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

@@ -118,19 +118,25 @@ case class ScaladocTastyInspector()(using ctx: DocContext) extends DocTastyInspe
 
     val defn = ctx.compilerContext.definitions
 
-    topLevels ++= Seq(
-      defn.AnyClass,
-      defn.MatchableClass,
-      // defn.AnyRefAlias,
-      defn.AnyKindClass,
-      // defn.andType,
-      // defn.orType,
-      defn.AnyValClass,
-      defn.NullClass,
-      defn.NothingClass,
-      defn.SingletonClass
-    ).map(s => "scala" -> parser.parseClasslike(s.asInstanceOf[parser.qctx.reflect.Symbol].tree.asInstanceOf[parser.qctx.reflect.ClassDef]))
-
+    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()
@@ -149,6 +155,24 @@ 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" -> oM.copy(
+      name = aM.name,
+      // dri = aM.dri,
+      signature = aM.signature,
+      sources = aM.sources,
+      origin = aM.origin,
+      inheritedFrom = aM.inheritedFrom,
+      graph = aM.graph,
+      docs = aM.docs,
+      directParents = aM.directParents,
+      parents = aM.parents,
+      knownChildren = aM.knownChildren,
+      companion = aM.companion,
+    )
 /** Parses a single Tasty compilation unit. */
 case class TastyParser(
   qctx: Quotes,
@@ -169,13 +193,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:
@@ -201,5 +218,3 @@ case class TastyParser(
       e.printStackTrace()
 
     docs.result()
-
-  // def parseClasslike(c: ClassDef): Member = parseClasslike(c)