Refactor snippet compiler args

Author: pikinier20

scaladoc-testcases/src/tests/snippetCompilerTest.scala

@@ -1,19 +1,19 @@
 package snippetCompiler
 
 /**
-  * ```scala sc:compile&failing
+  * ```scala sc:compile
   * def a = 2
   * val x = 1 + List()
   * a
   * ```
   *
-  * ```scala sc:compile&debug
+  * ```scala sc:failing
   * def a = 2
   * val x = 1 + List()
   * a
   * ```
   *
-  * ```scala sc:compile&failing
+  * ```scala sc:failing
   * def a = 2
   * ```
   *

scaladoc/src/dotty/tools/scaladoc/DocContext.scala

@@ -74,7 +74,7 @@ case class NavigationNode(name: String, dri: DRI, nested: Seq[NavigationNode])
 case class DocContext(args: Scaladoc.Args, compilerContext: CompilerContext):
   lazy val sourceLinks = SourceLinks.load(args.sourceLinks, args.revision)(using compilerContext)
 
-  lazy val snippetCompilerArgs = snippets.SnippetCompilerArgs.load(args.snippetCompilerArgs)(using compilerContext)
+  lazy val snippetCompilerArgs = snippets.SnippetCompilerArgs.load(args.snippetCompiler, args.snippetCompilerDebug)(using compilerContext)
 
   lazy val staticSiteContext = args.docsRoot.map(path => StaticSiteContext(
       File(path).getAbsoluteFile(),

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

@@ -49,7 +49,8 @@ object Scaladoc:
     includePrivateAPI: Boolean = false,
     docCanonicalBaseUrl: String = "",
     documentSyntheticTypes: Boolean = false,
-    snippetCompilerArgs: List[String] = Nil
+    snippetCompiler: List[String] = Nil,
+    snippetCompilerDebug: Boolean = false
   )
 
   def run(args: Array[String], rootContext: CompilerContext): Reporter =
@@ -191,7 +192,8 @@ object Scaladoc:
         visibilityPrivate.get,
         docCanonicalBaseUrl.get,
         YdocumentSyntheticTypes.get,
-        snippetCompilerArgs.get
+        snippetCompiler.get,
+        snippetCompilerDebug.get
       )
       (Some(docArgs), newContext)
     }

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

@@ -95,8 +95,11 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
   val YdocumentSyntheticTypes: Setting[Boolean] =
     BooleanSetting("-Ydocument-synthetic-types", "Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib", false)
 
-  val snippetCompilerArgs: Setting[List[String]] =
-    MultiStringSetting("-snippet-compiler-args", "snippet-compiler-args", snippets.SnippetCompilerArgs.usage)
+  val snippetCompiler: Setting[List[String]] =
+    MultiStringSetting("-snippet-compiler", "snippet-compiler", snippets.SnippetCompilerArgs.usage)
+
+  val snippetCompilerDebug: Setting[Boolean] =
+    BooleanSetting("-snippet-compiler-debug", snippets.SnippetCompilerArgs.debugUsage, false)
 
   def scaladocSpecificSettings: Set[Setting[_]] =
-    Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompilerArgs)
+    Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompiler, snippetCompilerDebug)

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

@@ -10,19 +10,11 @@ import dotty.tools.scaladoc.snippets._
 
 class DocRender(signatureRenderer: SignatureRenderer, snippetChecker: SnippetChecker)(using ctx: DocContext):
 
-  private val snippetCheckingFuncFromMember: Member => SnippetChecker.SnippetCheckingFunc =
+  private def snippetCheckingFuncFromMember: Member => SnippetChecker.SnippetCheckingFunc =
     (m: Member) => {
-      (str: String, lineOffset: SnippetChecker.LineOffset, argOverride: Option[SnippetCompilerArg]) => {
-          val pathBasedArg = ctx.snippetCompilerArgs.get(m).fold(
-            SnippetCompilerArg.default
-          )(
-            _ + SnippetCompilerArg.default
-          )
-          val arg = argOverride.fold(
-            pathBasedArg
-          )(
-            _ + pathBasedArg
-          )
+      (str: String, lineOffset: SnippetChecker.LineOffset, argOverride: Option[SCFlags]) => {
+          val pathBasedArg = ctx.snippetCompilerArgs.get(m)
+          val arg = argOverride.fold(pathBasedArg)(pathBasedArg.overrideFlag(_))
 
           snippetChecker.checkSnippet(str, m.docs.map(_.snippetCompilerData), arg, lineOffset).foreach { _ match {
               case r: SnippetCompilationResult if !r.isSuccessful =>

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetChecker.scala

@@ -20,7 +20,7 @@ class SnippetChecker()(using ctx: DocContext):
     arg: SnippetCompilerArg,
     lineOffset: SnippetChecker.LineOffset
   ): Option[SnippetCompilationResult] = {
-    if arg.is(SCFlags.Compile) then
+    if arg.flag != SCFlags.NoCompile then
       val wrapped = WrappedSnippet(
         snippet,
         data.map(_.packageName),
@@ -45,4 +45,4 @@ class SnippetChecker()(using ctx: DocContext):
 
 object SnippetChecker:
   type LineOffset = Int
-  type SnippetCheckingFunc = (String, LineOffset, Option[SnippetCompilerArg]) => Unit
+  type SnippetCheckingFunc = (String, LineOffset, Option[SCFlags]) => Unit

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetCompiler.scala

@@ -62,17 +62,17 @@ class SnippetCompiler(
 
   private def additionalMessages(wrappedSnippet: WrappedSnippet, arg: SnippetCompilerArg, context: Context): Seq[SnippetCompilerMessage] = {
     (
-      Option.when(arg.is(SCFlags.Fail) && !context.reporter.hasErrors)(
+      Option.when(arg.flag == SCFlags.Fail && !context.reporter.hasErrors)(
         SnippetCompilerMessage(None, "Snippet should not compile but compiled succesfully", MessageLevel.Error)
       ) ++
-      Option.when(arg.is(SCFlags.Debug))(
+      Option.when(arg.debug && !isSuccessful(arg, context))(
         SnippetCompilerMessage(None, s"\n${wrappedSnippet.snippet}", MessageLevel.Debug)
       )
     ).toList
   }
 
   private def isSuccessful(arg: SnippetCompilerArg, context: Context): Boolean = {
-    if arg.is(SCFlags.Fail) then context.reporter.hasErrors
+    if arg.flag == SCFlags.Fail then context.reporter.hasErrors
     else !context.reporter.hasErrors
   }
 

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetCompilerArgs.scala

@@ -1,95 +1,64 @@
 package dotty.tools.scaladoc
 package snippets
 
-case class SnippetCompilerArg(flags: Set[SCFlags]):
-  def is(flag: SCFlags): Boolean = flags.contains(flag)
-  def +(other: SnippetCompilerArg): SnippetCompilerArg = {
-    val allNoncompatbileFlags = flags.flatMap(_.forbiddenFlags)
-    val compatibleFlags = other.flags.filter(flag => !allNoncompatbileFlags.contains(flag))
-    copy(flags = flags ++ compatibleFlags)
-  }
-
-object SnippetCompilerArg:
-  def default: SnippetCompilerArg = SnippetCompilerArg(
-    Set(SCFlags.NoCompile)
-  )
+case class SnippetCompilerArg(flag: SCFlags, debug: Boolean):
+  def overrideFlag(f: SCFlags): SnippetCompilerArg = copy(flag = f)
 
-sealed trait SCFlags(val flagName: String, val forbiddenFlags: Set[SCFlags])
+sealed trait SCFlags(val flagName: String)
 
 object SCFlags:
-  case object Compile extends SCFlags("compile", Set(NoCompile))
-  case object NoCompile extends SCFlags("nocompile", Set(Compile))
-  case object Fail extends SCFlags("failing", Set())
-  case object Debug extends SCFlags("debug", Set())
+  case object Compile extends SCFlags("compile")
+  case object NoCompile extends SCFlags("nocompile")
+  case object Fail extends SCFlags("failing")
 
-  def values: Seq[SCFlags] = Seq(Compile, NoCompile, Fail, Debug)
+  def values: Seq[SCFlags] = Seq(Compile, NoCompile, Fail)
 
-case class SnippetCompilerArgs(scArgs: PathBased[SnippetCompilerArg]):
-  def get(member: Member): Option[SnippetCompilerArg] = member.sources.flatMap(s => scArgs.get(s.path).map(_.elem))
+case class SnippetCompilerArgs(scFlags: PathBased[SCFlags], val debug: Boolean, defaultFlag: SCFlags):
+  def get(member: Member): SnippetCompilerArg =
+    member.sources
+      .flatMap(s => scFlags.get(s.path).map(_.elem))
+      .fold(SnippetCompilerArg(defaultFlag, debug))(SnippetCompilerArg(_, debug))
 
 object SnippetCompilerArgs:
   val usage =
     """
     |Snippet compiler arguments provide a way to configure snippet checking.
     |
     |This setting accept list of arguments in format:
-    |arg := [path=]flag{&flag}
+    |args := arg{,arg}
+    |arg := [path=]flag
     |where path is a prefix of source paths to members to which argument should be set.
     |
     |If path is not present, argument will be used as default.
     |
     |Available flags:
-    |compile - Enables snippet checking. Cannot be used with nocompile.
-    |nocompile - Disables snippet checking. Cannot be used with compile.
+    |compile - Enables snippet checking.
+    |nocompile - Disables snippet checking.
+    |failing - Enables snippet checking, asserts that snippet doesn't compile.
     |
     """.stripMargin
 
-  def load(args: List[String])(using CompilerContext): SnippetCompilerArgs = {
-    PathBased.parse[SnippetCompilerArg](args)(using SnippetCompilerArgParser) match {
+  val debugUsage = """
+  |Setting this option causes snippet compiler to print snippet as it is compiled (after wrapping).
+  """.stripMargin
+
+  def load(args: List[String], debug: Boolean, defaultFlag: SCFlags = SCFlags.NoCompile)(using CompilerContext): SnippetCompilerArgs = {
+    PathBased.parse[SCFlags](args)(using SCFlagsParser) match {
       case PathBased.ParsingResult(errors, res) =>
-        if errors.nonEmpty then report.warning(
-          s"""Got following errors during snippet compiler args parsing:
+        if errors.nonEmpty then report.warning(s"""
+            |Got following errors during snippet compiler args parsing:
             |$errors
             |
-            |${usage}
+            |$usage
             |""".stripMargin
         )
-        SnippetCompilerArgs(res)
+        SnippetCompilerArgs(res, debug, defaultFlag)
     }
   }
 
-object SnippetCompilerArgParser extends ArgParser[SnippetCompilerArg]:
-  def parse(s: String): Either[String, SnippetCompilerArg] = {
-    val flagStrings = s.split("&")
-    val (parsed, errors) = flagStrings.map(flag => SCFlags.values.find(_.flagName == flag).fold(
-        Left(s"$flag: No such flag found.")
-      )(
-        Right(_)
-      )
-    ).partition(_.isRight)
-
-
-    val (flags, errors2) = parsed.collect {
-      case Right(flag) => flag
-    } match {
-      case list =>
-        list.map(f =>
-          list.find(elem =>
-            f.forbiddenFlags.contains(elem)
-          ) match {
-              case Some(forbiddenElem) => Left(s"${f.flagName}: Cannot be used with flag: ${forbiddenElem.flagName}")
-              case None => Right(f)
-            }
-        ).partition(_.isRight)
-    }
-
-    val checkedFlags = flags.collect {
-      case Right(flag) => flag
-    }.toSet
-
-    val allErrors = (errors ++ errors2).collect {
-      case Left(error) => error
-    }.toList
-
-    if !allErrors.isEmpty then Left(allErrors.mkString("\n")) else Right(SnippetCompilerArg(checkedFlags))
+object SCFlagsParser extends ArgParser[SCFlags]:
+  def parse(s: String): Either[String, SCFlags] = {
+    SCFlags.values
+      .find(_.flagName == s)
+      .fold(Left(s"$s: No such flag found."))(Right(_))
   }

scaladoc/src/dotty/tools/scaladoc/tasty/comments/markdown/DocFlexmarkExtension.scala

@@ -59,7 +59,7 @@ case class DocFlexmarkRenderer(renderLink: (DocLink, String) => String, snippetC
           info.split(" ")
             .find(_.startsWith("sc:"))
             .map(_.stripPrefix("sc:"))
-            .map(snippets.SnippetCompilerArgParser.parse)
+            .map(snippets.SCFlagsParser.parse)
             .flatMap(_.toOption)
         snippetCheckingFunc(node.getContentChars.toString, node.getStartLineNumber, argOverride)
         c.delegateRender()