Documentation in the Suggestions Database

RELEASES.md

@@ -36,6 +36,8 @@
 - Added support for reading and writing byte ranges in files remotely
   ([#1795](https://github.com/enso-org/enso/pull/1795)). This allows the IDE to
   transfer files to a remote back-end in a streaming fashion.
+- Added `documentationHtml` field to Suggestions database entry
+  ([#1791](https://github.com/enso-org/enso/pull/1791))
 
 ## Libraries
 

build.sbt

@@ -1064,6 +1064,7 @@ lazy val runtime = (project in file("engine/runtime"))
   .dependsOn(searcher)
   .dependsOn(testkit % Test)
   .dependsOn(`logging-utils`)
+  .dependsOn(`docs-generator`)
 
 /* Note [Unmanaged Classpath]
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~

engine/language-server/src/main/scala/org/enso/languageserver/search/SearchProtocol.scala

@@ -204,6 +204,7 @@ object SearchProtocol {
       * @param selfType the self type to update
       * @param returnType the return type to update
       * @param documentation the documentation string to update
+      * @param documentationHtml the HTML documentation to update
       * @param scope the scope to update
       */
     case class Modify(
@@ -214,6 +215,7 @@ object SearchProtocol {
       selfType: Option[FieldUpdate[String]]                  = None,
       returnType: Option[FieldUpdate[String]]                = None,
       documentation: Option[FieldUpdate[String]]             = None,
+      documentationHtml: Option[FieldUpdate[String]]         = None,
       scope: Option[FieldUpdate[Suggestion.Scope]]           = None
     ) extends SuggestionsDatabaseUpdate
 

engine/language-server/src/main/scala/org/enso/languageserver/search/SuggestionsHandler.scala

@@ -467,7 +467,9 @@ final class SuggestionsHandler(
                   arguments     = m.arguments.map(_.map(toApiArgumentAction)),
                   returnType    = m.returnType.map(fieldUpdate),
                   documentation = m.documentation.map(fieldUpdateOption),
-                  scope         = m.scope.map(fieldUpdate)
+                  documentationHtml =
+                    m.documentationHtml.map(fieldUpdateOption),
+                  scope = m.scope.map(fieldUpdate)
                 )
               }
           }

engine/language-server/src/test/scala/org/enso/languageserver/search/Suggestions.scala

@@ -8,12 +8,13 @@ import org.enso.polyglot.Suggestion
 object Suggestions {
 
   val atom: Suggestion.Atom = Suggestion.Atom(
-    externalId    = None,
-    module        = "Test.Main",
-    name          = "MyType",
-    arguments     = Vector(Suggestion.Argument("a", "Any", false, false, None)),
-    returnType    = "MyAtom",
-    documentation = None
+    externalId        = None,
+    module            = "Test.Main",
+    name              = "MyType",
+    arguments         = Vector(Suggestion.Argument("a", "Any", false, false, None)),
+    returnType        = "MyAtom",
+    documentation     = None,
+    documentationHtml = None
   )
 
   val method: Suggestion.Method = Suggestion.Method(
@@ -24,9 +25,10 @@ object Suggestions {
       Suggestion.Argument("this", "MyType", false, false, None),
       Suggestion.Argument("foo", "Number", false, true, Some("42"))
     ),
-    selfType      = "MyType",
-    returnType    = "Number",
-    documentation = Some("Lovely")
+    selfType          = "MyType",
+    returnType        = "Number",
+    documentation     = Some("Lovely"),
+    documentationHtml = Some("<p>Lovely</p>")
   )
 
   val function: Suggestion.Function = Suggestion.Function(
@@ -60,9 +62,10 @@ object Suggestions {
       Suggestion.Argument("this", "Any", false, false, None),
       Suggestion.Argument("that", "Any", false, false, None)
     ),
-    selfType      = "Any",
-    returnType    = "Any",
-    documentation = Some("Lovely")
+    selfType          = "Any",
+    returnType        = "Any",
+    documentation     = Some("Lovely"),
+    documentationHtml = Some("<p>Lovely</p>")
   )
 
   val methodOnNumber: Suggestion.Method = Suggestion.Method(
@@ -72,9 +75,10 @@ object Suggestions {
     arguments = Vector(
       Suggestion.Argument("this", "Number", false, false, None)
     ),
-    selfType      = "Number",
-    returnType    = "Number",
-    documentation = None
+    selfType          = "Number",
+    returnType        = "Number",
+    documentation     = None,
+    documentationHtml = None
   )
 
   val methodOnInteger: Suggestion.Method = Suggestion.Method(
@@ -84,9 +88,10 @@ object Suggestions {
     arguments = Vector(
       Suggestion.Argument("that", "Number", false, false, None)
     ),
-    selfType      = "Integer",
-    returnType    = "Number",
-    documentation = Some("Blah, blah")
+    selfType          = "Integer",
+    returnType        = "Number",
+    documentation     = Some("Blah, blah"),
+    documentationHtml = Some("<p>Blah, blah</p>")
   )
 
   val all = Seq(

engine/language-server/src/test/scala/org/enso/languageserver/search/SuggestionsHandlerSpec.scala

@@ -350,12 +350,13 @@ class SuggestionsHandlerSpec
 
         val moduleName = "Test.Foo"
         val moduleAtom = Suggestion.Atom(
-          externalId    = None,
-          module        = moduleName,
-          name          = "Foo",
-          arguments     = Vector(),
-          returnType    = moduleName,
-          documentation = None
+          externalId        = None,
+          module            = moduleName,
+          name              = "Foo",
+          arguments         = Vector(),
+          returnType        = moduleName,
+          documentation     = None,
+          documentationHtml = None
         )
         val fooAtom = moduleAtom.copy(returnType = "Test.Foo.Foo")
 

engine/language-server/src/test/scala/org/enso/languageserver/websocket/json/SuggestionsHandlerEventsTest.scala

@@ -7,13 +7,13 @@ import org.enso.languageserver.search.Suggestions
 import org.enso.languageserver.websocket.json.{SearchJsonMessages => json}
 import org.enso.polyglot.data.Tree
 import org.enso.polyglot.runtime.Runtime.Api
-import org.enso.testkit.RetrySpec
+import org.enso.testkit.FlakySpec
 
-class SuggestionsHandlerEventsTest extends BaseServerTest with RetrySpec {
+class SuggestionsHandlerEventsTest extends BaseServerTest with FlakySpec {
 
   "SuggestionsHandlerEvents" must {
 
-    "send suggestions database notifications" taggedAs Retry in {
+    "send suggestions database notifications" taggedAs Flaky in {
       val client = getInitialisedWsClient()
 
       client.send(json.acquireSuggestionsDatabaseUpdatesCapability(0))
@@ -126,7 +126,8 @@ class SuggestionsHandlerEventsTest extends BaseServerTest with RetrySpec {
                   ],
                   "selfType" : "MyType",
                   "returnType" : "Number",
-                  "documentation" : "Lovely"
+                  "documentation" : "Lovely",
+                  "documentationHtml" : "<p>Lovely</p>"
                 }
               }
             ],
@@ -307,6 +308,26 @@ class SuggestionsHandlerEventsTest extends BaseServerTest with RetrySpec {
           "id" : 0,
           "result" : {
             "entries" : [
+            {
+                "id" : 4,
+                "suggestion" : {
+                  "type" : "local",
+                  "externalId" : "dc077227-d9b6-4620-9b51-792c2a69419d",
+                  "module" : "Test.Main",
+                  "name" : "x",
+                  "returnType" : "Number",
+                  "scope" : {
+                    "start" : {
+                      "line" : 21,
+                      "character" : 0
+                    },
+                    "end" : {
+                      "line" : 89,
+                      "character" : 0
+                    }
+                  }
+                }
+              },
               {
                 "id" : 3,
                 "suggestion" : {
@@ -350,24 +371,6 @@ class SuggestionsHandlerEventsTest extends BaseServerTest with RetrySpec {
                   }
                 }
               },
-              {
-                "id" : 1,
-                "suggestion" : {
-                  "type" : "atom",
-                  "module" : "Test.Main",
-                  "name" : "MyType",
-                  "arguments" : [
-                    {
-                      "name" : "a",
-                      "reprType" : "Any",
-                      "isSuspended" : false,
-                      "hasDefault" : false,
-                      "defaultValue" : null
-                    }
-                  ],
-                  "returnType" : "MyAtom"
-                }
-              },
               {
                 "id" : 2,
                 "suggestion" : {
@@ -393,27 +396,26 @@ class SuggestionsHandlerEventsTest extends BaseServerTest with RetrySpec {
                   ],
                   "selfType" : "MyType",
                   "returnType" : "Number",
-                  "documentation" : "Lovely"
+                  "documentation" : "Lovely",
+                  "documentationHtml" : "<p>Lovely</p>"
                 }
               },
               {
-                "id" : 4,
+                "id" : 1,
                 "suggestion" : {
-                  "type" : "local",
-                  "externalId" : ${Suggestions.local.externalId.get},
+                  "type" : "atom",
                   "module" : "Test.Main",
-                  "name" : "x",
-                  "returnType" : "Number",
-                  "scope" : {
-                    "start" : {
-                      "line" : 21,
-                      "character" : 0
-                    },
-                    "end" : {
-                      "line" : 89,
-                      "character" : 0
+                  "name" : "MyType",
+                  "arguments" : [
+                    {
+                      "name" : "a",
+                      "reprType" : "Any",
+                      "isSuspended" : false,
+                      "hasDefault" : false,
+                      "defaultValue" : null
                     }
-                  }
+                  ],
+                  "returnType" : "MyAtom"
                 }
               }
             ],

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

@@ -132,7 +132,8 @@ object Suggestion {
     name: String,
     arguments: Seq[Argument],
     returnType: String,
-    documentation: Option[String]
+    documentation: Option[String],
+    documentationHtml: Option[String]
   ) extends Suggestion
       with ToLogString {
 
@@ -143,9 +144,11 @@ object Suggestion {
       s"module=$module," +
       s"name=$name," +
       s"arguments=${arguments.map(_.toLogString(shouldMask))}," +
-      s"returnType=$returnType,documentation=" +
-      (if (shouldMask) documentation.map(_ => STUB) else documentation) +
-      ")"
+      s"returnType=$returnType" +
+      s",documentation=" + (if (shouldMask) documentation.map(_ => STUB)
+                            else documentation) +
+      s",documentationHtml=" + (if (shouldMask) documentationHtml.map(_ => STUB)
+                                else documentationHtml) + ")"
   }
 
   /** A function defined on a type or a module.
@@ -165,7 +168,8 @@ object Suggestion {
     arguments: Seq[Argument],
     selfType: String,
     returnType: String,
-    documentation: Option[String]
+    documentation: Option[String],
+    documentationHtml: Option[String]
   ) extends Suggestion
       with ToLogString {
 
@@ -176,8 +180,11 @@ object Suggestion {
       s"name=$name," +
       s"arguments=${arguments.map(_.toLogString(shouldMask))}," +
       s"selfType=$selfType," +
-      s"returnType=$returnType,documentation=" +
-      (if (shouldMask) documentation.map(_ => STUB) else documentation) +
+      s"returnType=$returnType," +
+      s"documentation=" + (if (shouldMask) documentation.map(_ => STUB)
+                           else documentation) +
+      s",documentationHtml=" + (if (shouldMask) documentationHtml.map(_ => STUB)
+                                else documentationHtml) +
       ")"
   }
 

engine/polyglot-api/src/main/scala/org/enso/polyglot/runtime/Runtime.scala

@@ -567,13 +567,15 @@ object Runtime {
         * @param arguments the arguments to update
         * @param returnType the return type to update
         * @param documentation the documentation string to update
+        * @param documentationHtml the HTML documentation to update
         * @param scope the scope to update
         */
       case class Modify(
         externalId: Option[Option[Suggestion.ExternalId]] = None,
         arguments: Option[Seq[SuggestionArgumentAction]]  = None,
         returnType: Option[String]                        = None,
         documentation: Option[Option[String]]             = None,
+        documentationHtml: Option[Option[String]]         = None,
         scope: Option[Suggestion.Scope]                   = None
       ) extends SuggestionAction
           with ToLogString {
@@ -586,6 +588,9 @@ object Runtime {
           s"documentation=" +
           (if (shouldMask) documentation.map(_.map(_ => STUB))
            else documentation) +
+          s"documentationHtml=" +
+          (if (shouldMask) documentationHtml.map(_.map(_ => STUB))
+           else documentationHtml) +
           s",scope=$scope" +
           ")"
       }