Update lsp generation for more accurate documentation

internal/lsp/lsproto/_generate/generate.mjs

@@ -58,21 +58,38 @@ function writeLine(s) {
     write("\n");
 }
 
+/**
+ * @param {{
+ * 		documentation?: string,
+ * 		proposed?: boolean,
+ * 		since?: string,
+ * 		sinceTags?: string[],
+ * 		deprecated?: string
+ * }} data
+ */
+function writeDocumentation(data) {
+    writeDescription(data.documentation);
+    writeSince(data.since, data.sinceTags);
+    writeProposed(data.proposed);
+    writeDeprecation(data.deprecated, data.documentation);
+}
+
 /**
  * @param {string | undefined} doc
  */
-function writeDocumentation(doc) {
+function writeDescription(doc) {
     if (doc) {
         const lines = doc.split("\n");
         for (let line of lines) {
             line = line.replace(/(\w ) +/g, "$1");
             line = line.replace(/\{@link(?:code)?.*?([^} ]+)\}/g, "$1");
-            line = line.replace(/@since (.*)/g, "Since: $1\n//");
-            if (line.startsWith("@deprecated")) {
-                continue;
-            }
-            if (line.startsWith("@proposed")) {
-                line = "Proposed.\n//";
+
+            if (
+                line.includes("@since") ||
+                line.startsWith("@deprecated") ||
+                line.startsWith("@proposed")
+            ) {
+                break;
             }
 
             write("// ");
@@ -81,15 +98,71 @@ function writeDocumentation(doc) {
     }
 }
 
+/**
+ * @param {boolean | undefined} proposed
+ */
+function writeProposed(proposed) {
+    if (proposed) {
+        writeLine("// ");
+        writeLine("// Proposed.");
+    }
+}
+
+/**
+ * @param {string | undefined} since
+ * @param {string[] | undefined} sinceTags
+ */
+function writeSince(since, sinceTags) {
+    if (since && !sinceTags) {
+        const sinceLines = since.split("\n");
+        writeSinceLines(sinceLines);
+    }
+    else if (sinceTags) {
+        for (const [idx, sinceTag] of sinceTags.entries()) {
+            const sinceLines = sinceTag.split("\n");
+            writeSinceLines(sinceLines);
+
+            if (idx !== sinceTags.length - 1) {
+                writeLine("// ");
+            }
+        }
+    }
+}
+
+/**
+ * @param {string[]} sinceLines
+ */
+function writeSinceLines(sinceLines) {
+    writeLine(`// Since: ${sinceLines[0]}`);
+
+    for (let i = 1; i < sinceLines.length; i++) {
+        writeLine(`// ${sinceLines[i]}`);
+    }
+}
+
 /**
  * @param {string | undefined} deprecated
+ * @param {string | undefined} doc
  */
-function writeDeprecation(deprecated) {
+function writeDeprecation(deprecated, doc) {
+    const inlineDeprecation = "is deprecated @since";
+
     if (deprecated) {
-        writeLine("//");
+        writeLine("// ");
         write("// Deprecated: ");
         writeLine(deprecated);
     }
+    else if (doc?.includes(inlineDeprecation)) {
+        const lines = doc.split("\n");
+        const matchingLine = lines.find(x => x.includes(inlineDeprecation));
+
+        if (matchingLine) {
+            const deprecationMessage = matchingLine.split(" @since")[0];
+            writeLine("// ");
+            write("// Deprecated: ");
+            writeLine(deprecationMessage);
+        }
+    }
 }
 
 /**
@@ -301,8 +374,7 @@ writeLine("");
 writeLine("// Structures\n");
 
 for (const t of model.structures) {
-    writeDocumentation(t.documentation);
-    writeDeprecation(t.deprecated);
+    writeDocumentation(t);
 
     writeLine("type " + t.name + " struct {");
 
@@ -324,8 +396,7 @@ for (const t of model.structures) {
     }
 
     for (const p of t.properties) {
-        writeDocumentation(p.documentation);
-        writeDeprecation(p.deprecated);
+        writeDocumentation(p);
 
         write(titleCase(p.name) + " ");
 
@@ -350,8 +421,7 @@ for (const t of model.structures) {
 writeLine("// Enumerations\n");
 
 for (const t of model.enumerations) {
-    writeDocumentation(t.documentation);
-    writeDeprecation(t.deprecated);
+    writeDocumentation(t);
 
     /** @type {string} */
     let underlyingType;
@@ -380,8 +450,7 @@ for (const t of model.enumerations) {
 
     writeLine("const (");
     for (const v of t.values) {
-        writeDocumentation(v.documentation);
-        writeDeprecation(v.deprecated);
+        writeDocumentation(v);
 
         write(t.name);
         write(v.name);
@@ -408,8 +477,7 @@ for (const t of model.enumerations) {
 writeLine("// Type aliases\n");
 
 for (const t of model.typeAliases) {
-    writeDocumentation(t.documentation);
-    writeDeprecation(t.deprecated);
+    writeDocumentation(t);
 
     if (t.name === "LSPAny") {
         writeLine("type LSPAny = any\n");
@@ -452,17 +520,15 @@ writeLine("}");
 writeLine("// Requests");
 writeLine("const (");
 for (const t of model.requests) {
-    writeDocumentation(t.documentation);
-    writeDeprecation(t.deprecated);
+    writeDocumentation(t);
     writeLine("Method" + methodNameToIdentifier(t.method) + ' Method = "' + t.method + '"');
 }
 writeLine(")\n");
 
 writeLine("// Notifications");
 writeLine("const (");
 for (const t of model.notifications) {
-    writeDocumentation(t.documentation);
-    writeDeprecation(t.deprecated);
+    writeDocumentation(t);
     writeLine("Method" + methodNameToIdentifier(t.method) + ' Method = "' + t.method + '"');
 }
 writeLine(")\n");