Infrastructure for enso --docs option & signature generator

engine/polyglot-api/src/main/scala/org/enso/polyglot/Module.scala

@@ -44,14 +44,6 @@ class Module(private val value: Value) {
   def evalExpression(code: String): Value =
     value.invokeMember(EVAL_EXPRESSION, code)
 
-  /** Triggers generation of documentation from module sources.
-    *
-    * @return value with `GENERATE_DOCS` invoked on it.
-    */
-  def generateDocs(): Value = {
-    value.invokeMember(GENERATE_DOCS)
-  }
-
   /** Triggers gathering of import statements from module sources.
     *
     * @return value with `GATHER_IMPORT_STATEMENTS` invoked on it.

engine/polyglot-api/src/main/scala/org/enso/polyglot/TopScope.scala

@@ -34,7 +34,24 @@ class TopScope(private val value: Value) {
     value.invokeMember(UNREGISTER_MODULE, qualifiedName): Unit
   }
 
-  def compile(shouldCompileDependencies: Boolean): Unit = {
-    value.invokeMember(COMPILE, shouldCompileDependencies)
+  def compile(
+    shouldCompileDependencies: Boolean
+  ): Unit = {
+    compile(shouldCompileDependencies, None)
   }
+  def compile(
+    shouldCompileDependencies: Boolean,
+    generateDocs: Option[String]
+  ): Unit = {
+    val docsArg = generateDocs.map {
+      case "api" => "api"
+      case _     => "md"
+    }
+    value.invokeMember(
+      COMPILE,
+      shouldCompileDependencies,
+      docsArg.getOrElse(false)
+    )
+  }
+
 }

engine/runner/src/main/java/org/enso/runner/Main.java

@@ -146,8 +146,13 @@ private static Options buildOptions() {
             .build();
     var docs =
         cliOptionBuilder()
+            .hasArg(true)
+            .numberOfArgs(1)
+            .optionalArg(true)
             .longOpt(DOCS_OPTION)
-            .desc("Runs the Enso documentation generator.")
+            .desc(
+                "Runs the Enso documentation generator. Additional argument may specify format -"
+                    + " either the default `md` or `api`.")
             .build();
     var preinstall =
         cliOptionBuilder()
@@ -652,7 +657,7 @@ private void compile(
 
     var topScope = context.getTopScope();
     try {
-      topScope.compile(shouldCompileDependencies);
+      topScope.compile(shouldCompileDependencies, scala.Option.empty());
       throw exitSuccess();
     } catch (Throwable t) {
       logger.error("Unexpected internal error", t);
@@ -785,12 +790,16 @@ private void handleRun(
    * @param enableIrCaches are the IR caches enabled
    */
   private void genDocs(
-      String projectPath, Level logLevel, boolean logMasking, boolean enableIrCaches) {
-    if (projectPath.isEmpty()) {
-      println("Path hasn't been provided.");
+      String docsFormat,
+      String projectPath,
+      Level logLevel,
+      boolean logMasking,
+      boolean enableIrCaches) {
+    if (projectPath == null || projectPath.isEmpty()) {
+      println("Specify path to a project with --in-project option");
       throw exitFail();
     }
-    generateDocsFrom(projectPath, logLevel, logMasking, enableIrCaches);
+    generateDocsFrom(docsFormat, projectPath, logLevel, logMasking, enableIrCaches);
     throw exitSuccess();
   }
 
@@ -799,7 +808,7 @@ private void genDocs(
    * path.
    */
   private void generateDocsFrom(
-      String path, Level logLevel, boolean logMasking, boolean enableIrCaches) {
+      String docsFormat, String path, Level logLevel, boolean logMasking, boolean enableIrCaches) {
     var executionContext =
         new PolyglotContext(
             ContextFactory.create()
@@ -816,17 +825,8 @@ private void generateDocsFrom(
     var main = pkg.map(x -> x.mainFile());
 
     if (main.exists(x -> x.exists())) {
-      var mainFile = main.get();
-      var mainModuleName = pkg.get().moduleNameForFile(mainFile).toString();
       var topScope = executionContext.getTopScope();
-      var mainModule = topScope.getModule(mainModuleName);
-      var generated = mainModule.generateDocs();
-      println(generated.toString());
-
-      // TODO:
-      // - go through executed code and get all HTML docs
-      //   with their corresponding atoms/methods etc.
-      // - Save those to files
+      topScope.compile(false, scala.Option.apply(docsFormat == null ? "md" : docsFormat));
     }
   }
 
@@ -1164,7 +1164,11 @@ final void mainEntry(CommandLine line, Level logLevel, boolean logMasking) throw
     }
     if (line.hasOption(DOCS_OPTION)) {
       genDocs(
-          line.getOptionValue(IN_PROJECT_OPTION), logLevel, logMasking, shouldEnableIrCaches(line));
+          line.getOptionValue(DOCS_OPTION),
+          line.getOptionValue(IN_PROJECT_OPTION),
+          logLevel,
+          logMasking,
+          shouldEnableIrCaches(line));
     }
     if (line.hasOption(PREINSTALL_OPTION)) {
       preinstallDependencies(line.getOptionValue(IN_PROJECT_OPTION), logLevel);

engine/runtime-compiler/src/main/java/org/enso/compiler/dump/DocsDispatch.java

@@ -0,0 +1,53 @@
+package org.enso.compiler.dump;
+
+import java.io.IOException;
+import org.enso.compiler.core.ir.Module;
+import org.enso.compiler.core.ir.module.scope.Definition;
+import org.enso.compiler.core.ir.module.scope.definition.Method;
+import org.enso.pkg.QualifiedName;
+
+/**
+ * Class to use from {@link DocsGenerate} to dispatch individual IR elements to provided visitor.
+ */
+abstract class DocsDispatch {
+  static DocsDispatch create(DocsVisit visitor, Appendable writer) {
+    return new DocsDispatch() {
+      @Override
+      boolean dispatchModule(QualifiedName name, Module ir) throws IOException {
+        return visitor.visitModule(name, ir, writer);
+      }
+
+      @Override
+      void dispatchMethod(Definition.Type t, Method.Explicit m) throws IOException {
+        visitor.visitMethod(t, m, writer);
+      }
+
+      @Override
+      void dispatchConversion(Method.Conversion c) throws IOException {
+        visitor.visitConversion(c, writer);
+      }
+
+      @Override
+      boolean dispatchType(Definition.Type t) throws IOException {
+        return visitor.visitType(t, writer);
+      }
+
+      @Override
+      void dispatchConstructor(Definition.Type t, Definition.Data d) throws IOException {
+        visitor.visitConstructor(t, d, writer);
+      }
+    };
+  }
+
+  private DocsDispatch() {}
+
+  abstract boolean dispatchModule(QualifiedName name, Module ir) throws IOException;
+
+  abstract void dispatchMethod(Definition.Type t, Method.Explicit m) throws IOException;
+
+  abstract void dispatchConversion(Method.Conversion c) throws IOException;
+
+  abstract boolean dispatchType(Definition.Type t) throws IOException;
+
+  abstract void dispatchConstructor(Definition.Type t, Definition.Data d) throws IOException;
+}

engine/runtime-compiler/src/main/java/org/enso/compiler/dump/DocsEmitMarkdown.java

@@ -0,0 +1,59 @@
+package org.enso.compiler.dump;
+
+import java.io.IOException;
+import org.enso.compiler.core.IR;
+import org.enso.compiler.core.ir.Module;
+import org.enso.compiler.core.ir.module.scope.Definition;
+import org.enso.compiler.core.ir.module.scope.definition.Method;
+import org.enso.compiler.pass.resolve.DocumentationComments;
+import org.enso.compiler.pass.resolve.DocumentationComments$;
+import org.enso.pkg.QualifiedName;
+
+/** Visitor that emits documentation in markdown format. */
+final class DocsEmitMarkdown implements DocsVisit {
+
+  @Override
+  public boolean visitUnknown(IR ir, Appendable w) {
+    return true;
+  }
+
+  @Override
+  public boolean visitModule(QualifiedName name, Module module, Appendable w) throws IOException {
+    w.append("## Documentation for " + name + "\n");
+    writeDocs(module, w);
+    return true;
+  }
+
+  @Override
+  public void visitMethod(Definition.Type t, Method.Explicit m, Appendable w) throws IOException {
+    w.append("#### method " + m.methodName().name() + "\n");
+    writeDocs(m, w);
+  }
+
+  @Override
+  public void visitConversion(Method.Conversion c, Appendable w) throws IOException {
+    w.append("#### conversion " + c.methodName().name() + "\n");
+    writeDocs(c, w);
+  }
+
+  private void writeDocs(IR b, Appendable w) throws IOException {
+    var option = b.passData().get(DocumentationComments$.MODULE$);
+    if (option.isDefined()) {
+      var doc = (DocumentationComments.Doc) option.get();
+      w.append(doc.documentation());
+      w.append("\n\n\n");
+    }
+  }
+
+  @Override
+  public boolean visitType(Definition.Type t, Appendable w) throws IOException {
+    w.append("#### **type** " + t.name().name() + "\n");
+    return true;
+  }
+
+  @Override
+  public void visitConstructor(Definition.Type t, Definition.Data d, Appendable w)
+      throws IOException {
+    w.append("#### data " + d.name().name() + "\n");
+  }
+}

engine/runtime-compiler/src/main/java/org/enso/compiler/dump/DocsEmitSignatures.java

@@ -0,0 +1,63 @@
+package org.enso.compiler.dump;
+
+import static org.enso.scala.wrapper.ScalaConversions.asJava;
+
+import java.io.IOException;
+import org.enso.compiler.core.IR;
+import org.enso.compiler.core.ir.Module;
+import org.enso.compiler.core.ir.module.scope.Definition;
+import org.enso.compiler.core.ir.module.scope.definition.Method;
+import org.enso.pkg.QualifiedName;
+
+/** Visitor that emits documentation in markdown format. */
+final class DocsEmitSignatures implements DocsVisit {
+
+  @Override
+  public boolean visitUnknown(IR ir, Appendable w) throws IOException {
+    w.append("- Unknown IR " + ir.getClass().getName() + "\n");
+    return true;
+  }
+
+  @Override
+  public boolean visitModule(QualifiedName name, Module module, Appendable w) throws IOException {
+    w.append("## Enso Signatures 1.0\n");
+    w.append("## module " + name + "\n");
+    return true;
+  }
+
+  @Override
+  public void visitMethod(Definition.Type t, Method.Explicit m, Appendable w) throws IOException {
+    if (t != null) {
+      w.append("    - ");
+    } else {
+      if (m.typeName().isDefined()) {
+        var fqn = DocsUtils.toFqnOrSimpleName(m.typeName().get());
+        w.append(fqn + ".");
+      }
+    }
+    w.append(DocsVisit.toSignature(m) + "\n");
+  }
+
+  @Override
+  public void visitConversion(Method.Conversion c, Appendable w) throws IOException {
+    w.append("#### conversion " + c.methodName().name() + "\n");
+  }
+
+  @Override
+  public boolean visitType(Definition.Type t, Appendable w) throws IOException {
+    var sb = new StringBuilder();
+    sb.append("- type ").append(t.name().name());
+    for (var a : asJava(t.params())) {
+      sb.append(" ").append(DocsVisit.toSignature(a));
+    }
+    sb.append("\n");
+    w.append(sb.toString());
+    return true;
+  }
+
+  @Override
+  public void visitConstructor(Definition.Type t, Definition.Data d, Appendable w)
+      throws IOException {
+    w.append("    - " + DocsVisit.toSignature(d) + "\n");
+  }
+}