Generate documentation (#930)

- annotate doc comments in Tree
- right now this is only implemented as a POC (and breaks some Effekt
code), we should combine this with the current efforts of annotating the
tree with positions and types
- add flags `show-documentation` and `write-documentation` for
generating JSONs of documented nodes
- these JSONs can be later used to generate API documentation for the
website

---------

Co-authored-by: David Binder <[email protected]>
Co-authored-by: Tim Süberkrüb <[email protected]>

Author: 3 people

effekt/jvm/src/main/scala/effekt/Driver.scala

@@ -11,7 +11,7 @@ import kiama.parsing.ParseResult
 import kiama.util.{ IO, Source }
 import effekt.util.messages.{ BufferedMessaging, CompilerPanic, EffektError, EffektMessaging, FatalPhaseError }
 import effekt.util.paths.file
-import effekt.util.{ AnsiColoredMessaging, MarkdownSource, getOrElseAborting }
+import effekt.util.{ JSONDocumentationGenerator, AnsiColoredMessaging, MarkdownSource, getOrElseAborting }
 
 import scala.sys.process.Process
 
@@ -66,8 +66,9 @@ trait Driver extends kiama.util.Compiler[EffektConfig, EffektError] { outer =>
           }
         }
 
-        // we are in one of three exclusive modes: LSPServer, Compile, Run
-        if (config.server()) { compiler.runFrontend(src) }
+        // we are in one of four exclusive modes: Documenter, LSPServer, Compile, Run
+        if (config.documenter()) { documenter(source, config)(context) }
+        else if (config.server()) { compiler.runFrontend(src) }
         else if (config.interpret()) { compile() foreach runner.eval }
         else if (config.build()) { compile() foreach runner.build }
         else if (config.compile()) { compile() }
@@ -126,6 +127,25 @@ trait Driver extends kiama.util.Compiler[EffektConfig, EffektError] { outer =>
       }
   }
 
+  def generateDocumentation(ast: ModuleDecl, source: Source)(using C: Context): String =
+    JSONDocumentationGenerator(ast, source.name).content
+
+  def showDocumentation(ast: ModuleDecl, source: Source)(using C: Context): Unit =
+    println(generateDocumentation(ast, source))
+
+  def writeDocumentation(ast: ModuleDecl, source: Source, output: String)(using C: Context): Unit =
+    val name = source.name.split("/").last + ".json"
+    IO.createFile((output / name).unixPath, generateDocumentation(ast, source))
+
+  def documenter(source: Source, config: EffektConfig)(implicit C: Context): Unit =
+    C.compiler.runFrontend(source)
+    val astOpt = C.compiler.getAST(source)
+    if (astOpt.isEmpty) return
+
+    val out = config.outputPath().getAbsolutePath
+    if (config.writeDocumentation()) writeDocumentation(astOpt.get, source, out)
+    if (config.showDocumentation()) showDocumentation(astOpt.get, source)
+
   /**
    * Overridden in [[Server]] to also publish core and js compilation results to VSCode
    */

effekt/jvm/src/main/scala/effekt/EffektConfig.scala

@@ -155,6 +155,24 @@ class EffektConfig(args: Seq[String]) extends REPLConfig(args.takeWhile(_ != "--
     group = debugging
   )
 
+  val showDocumentation: ScallopOption[Boolean] = toggle(
+    "show-documentation",
+    descrYes = "Show all documented statements as a JSON",
+    default = Some(false),
+    noshort = true,
+    prefix = "no-",
+    group = debugging
+  )
+
+  val writeDocumentation: ScallopOption[Boolean] = toggle(
+    "write-documentation",
+    descrYes = "Write all documented statements to a JSON in the output directory",
+    default = Some(false),
+    noshort = true,
+    prefix = "no-",
+    group = debugging
+  )
+
   val time: ScallopOption[String] = choice(
     choices = Seq("text", "json"),
     name = "time",
@@ -232,6 +250,8 @@ class EffektConfig(args: Seq[String]) extends REPLConfig(args.takeWhile(_ != "--
 
   def repl(): Boolean = filenames().isEmpty && !server() && !compile()
 
+  def documenter(): Boolean = showDocumentation() || writeDocumentation()
+
   def timed(): Boolean = time.isSupplied && !server()
 
   validateFilesIsDirectory(includePath)

effekt/jvm/src/main/scala/effekt/Repl.scala

@@ -316,7 +316,7 @@ class Repl(driver: Driver) extends REPL[Tree, EffektConfig, EffektError] {
       val fullSpan = Span(source, 0, source.content.length, origin = Origin.Synthesized)
       ModuleDecl("interactive", includes,
         definitions :+ FunDef(IdDef("main", fakeSpan), Many.empty(fakeSpan), Many.empty(fakeSpan), Many.empty(fakeSpan), Maybe.None(fakeSpan),
-          body, fullSpan), fullSpan)
+          body, None, fullSpan), None, fullSpan)
     }
 
     def makeEval(source: Source, expr: Term): ModuleDecl = {

effekt/jvm/src/test/scala/effekt/LSPTests.scala

@@ -1188,9 +1188,11 @@ class LSPTests extends FunSuite {
              |          Span(StringSource(def main() = <>, file://test.effekt), 13, 15, Real())
              |        )
              |      ),
+             |      None(),
              |      Span(StringSource(def main() = <>, file://test.effekt), 0, 15, Real())
              |    )
              |  ),
+             |  None(),
              |  Span(StringSource(def main() = <>, file://test.effekt), 0, 15, Real())
              |)""".stripMargin
 
@@ -1244,6 +1246,7 @@ class LSPTests extends FunSuite {
              |  List(foo_whatever)
              |)""".stripMargin
 
+
       val receivedIRContent = client.receivedIR()
       assertEquals(receivedIRContent.length, 1)
       assertIREquals(receivedIRContent.head.content, expectedIRContents)