Apply requested changes

Author: BarkingBad

docs/docs/reference/other-new-features/opaques.md

@@ -30,7 +30,7 @@ object MyMath:
 
 end MyMath
 ```
-
+xc
 This introduces `Logarithm` as a new abstract type, which is implemented as `Double`.
 The fact that `Logarithm` is the same as `Double` is only known in the scope where
 `Logarithm` is defined which in the above example corresponds to the object `MyMath`.

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

@@ -121,7 +121,14 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
     BooleanSetting("-Yapi-subdirectory", "Put the API documentation pages inside a directory `api/`", false)
 
   val projectFormat: Setting[String] =
-    StringSetting("-format", "format of the static site output", "Format of the static site output", "html")
+    ChoiceSetting(
+      "-format",
+      "format of the static site output",
+      "Format of the static site output. The default value is html, which converts all static articles into a webpage. " +
+        "The md format only preprocess markdown files and should not be used as a direct output, but rather as a sources generator for an outer templating engine like Jekyll",
+      List("html", "md"),
+      "html"
+    )
 
   def scaladocSpecificSettings: Set[Setting[_]] =
     Set(sourceLinks, syntax, revision, externalDocumentationMappings, socialLinks, skipById, skipByRegex, deprecatedSkipPackages, docRootContent, snippetCompiler, generateInkuire)

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

@@ -12,17 +12,17 @@ import com.vladsch.flexmark.util.options._
 import com.vladsch.flexmark.util.sequence.BasedSequence
 import com.vladsch.flexmark._
 
+/**
+ * SnippetFormattingExtension is a clone of the [[SnippetRenderingExtension]] used as a fallback strategy when the `-format` setting is set up to `md`
+ */
 object SnippetFormattingExtension extends Formatter.FormatterExtension:
 
   def rendererOptions(opt: MutableDataHolder): Unit = ()
 
   object ExtendedFencedCodeBlockHandler extends CustomNodeFormatter[ExtendedFencedCodeBlock]:
     override def render(node: ExtendedFencedCodeBlock, c: NodeFormatterContext, markdown: MarkdownWriter): Unit =
       markdown.append(
-        SnippetRenderer.renderSnippetWithMessages(
-          node.codeBlock.getContentChars.toString.split("\n").map(_ + "\n").toSeq,
-          node.compilationResult.toSeq.flatMap(_.messages)
-        )
+        SnippetRenderer.renderSnippetWithMessages(node)
       )
 
   object Format extends NodeFormatter:

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

@@ -137,4 +137,11 @@ object SnippetRenderer:
   def renderSnippetWithMessages(snippetName: Option[String], codeLines: Seq[String], messages: Seq[SnippetCompilerMessage]): String =
     val transformedLines = wrapCodeLines.andThen(addCompileMessages(messages)).apply(codeLines).map(_.toHTML)
     val codeHTML = s"""<code class="language-scala">${transformedLines.mkString("")}</code>"""
-    s"""<div class="snippet"><div class="buttons"></div><pre>$codeHTML</pre>${snippetName.fold("")(snippetLabel(_))}</div>"""
+    s"""<div class="snippet"><div class="buttons"></div><pre>$codeHTML</pre>${snippetName.fold("")(snippetLabel(_))}</div>"""
+
+  def renderSnippetWithMessages(node: ExtendedFencedCodeBlock): String =
+    renderSnippetWithMessages(
+      node.name,
+      node.codeBlock.getContentChars.toString.split("\n").map(_ + "\n").toSeq,
+      node.compilationResult.toSeq.flatMap(_.messages)
+    )

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

@@ -13,16 +13,17 @@ import com.vladsch.flexmark.util.options._
 import com.vladsch.flexmark.util.sequence.BasedSequence
 import com.vladsch.flexmark._
 
+/**
+ * SnippetRenderingExtension is responsible for running an analysis for scala codeblocks in the static documentation/scaladoc comments.
+ * For each codeblock we run compiler to check whether snippet works in the newest scala version and to produce rich html codeblocks with
+ * compiler warnings/errors for IDE-like live experience.
+ */
 object SnippetRenderingExtension extends HtmlRenderer.HtmlRendererExtension:
   def rendererOptions(opt: MutableDataHolder): Unit = ()
   object ExtendedFencedCodeBlockHandler extends CustomNodeRenderer[ExtendedFencedCodeBlock]:
     override def render(node: ExtendedFencedCodeBlock, c: NodeRendererContext, html: HtmlWriter): Unit =
       html.raw(
-        SnippetRenderer.renderSnippetWithMessages(
-          node.name,
-          node.codeBlock.getContentChars.toString.split("\n").map(_ + "\n").toSeq,
-          node.compilationResult.toSeq.flatMap(_.messages)
-        )
+        SnippetRenderer.renderSnippetWithMessages(node)
       )
 
   object Render extends NodeRenderer:
@@ -35,4 +36,4 @@ object SnippetRenderingExtension extends HtmlRenderer.HtmlRendererExtension:
     override def create(options: DataHolder): NodeRenderer = Render
 
   def extend(htmlRendererBuilder: HtmlRenderer.Builder, tpe: String): Unit =
-    htmlRendererBuilder.nodeRendererFactory(Factory)
+    htmlRendererBuilder.nodeRendererFactory(Factory)