Skip to content

Update lsp generation for more accurate documentation #742

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed

Update lsp generation for more accurate documentation #742

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
dd36be1
Update lsp generation for more accurate documentation
dyl10s Apr 3, 2025
e146334
format file
dyl10s Apr 3, 2025
690bde3
condense repeated function calls
dyl10s Apr 3, 2025
2f42222
Merge branch 'main' into update-lsp-generation
dyl10s Apr 4, 2025
7ab7bdc
join params into single object with new type
dyl10s Apr 10, 2025
a1f6ee5
switch doc to documentation
dyl10s Apr 10, 2025
935726d
Merge branch 'microsoft:main' into update-lsp-generation
dyl10s Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 87 additions & 23 deletions internal/lsp/lsproto/_generate/generate.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,19 +60,34 @@ function writeLine(s) {

/**
* @param {string | undefined} doc
* @param {string | undefined} proposed,
* @param {string | undefined} since,
* @param {string | undefined} sinceTags,
* @param {string | undefined} deprecated
*/
function writeDocumentation(doc) {
function writeDocumentation(doc, proposed, since, sinceTags, deprecated) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should really just accept a single parameter of a shape that includes all of these props, looking at each of the calls.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I swapped this to an inline object type. I looked in metaModelSchema.mts to see if there was a base type that each of these objects extended but didn't find one. Let me know if you have a better idea here.

writeDescription(doc);
writeSince(since, sinceTags);
writeProposed(proposed);
writeDeprecation(deprecated, doc);
}

/**
* @param {string | undefined} 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("// ");
Expand All @@ -81,15 +96,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 inlineDeprication = "is deprecated @since";

if (deprecated) {
writeLine("//");
writeLine("// ");
write("// Deprecated: ");
writeLine(deprecated);
}
else if (doc?.includes(inlineDeprication)) {
const lines = doc.split("\n");
const matchingLine = lines.find(x => x.includes(inlineDeprication));

if (matchingLine) {
const depricationMessage = matchingLine.split(" @since")[0];
writeLine("// ");
write("// Deprecated: ");
writeLine(depricationMessage);
}
}
}

/**
Expand Down Expand Up @@ -301,8 +372,7 @@ writeLine("");
writeLine("// Structures\n");

for (const t of model.structures) {
writeDocumentation(t.documentation);
writeDeprecation(t.deprecated);
writeDocumentation(t.documentation, t.proposed, t.since, t.sinceTags, t.deprecated);

writeLine("type " + t.name + " struct {");

Expand All @@ -324,8 +394,7 @@ for (const t of model.structures) {
}

for (const p of t.properties) {
writeDocumentation(p.documentation);
writeDeprecation(p.deprecated);
writeDocumentation(p.documentation, p.proposed, p.since, p.sinceTags, p.deprecated);

write(titleCase(p.name) + " ");

Expand All @@ -350,8 +419,7 @@ for (const t of model.structures) {
writeLine("// Enumerations\n");

for (const t of model.enumerations) {
writeDocumentation(t.documentation);
writeDeprecation(t.deprecated);
writeDocumentation(t.documentation, t.proposed, t.since, t.sinceTags, t.deprecated);

/** @type {string} */
let underlyingType;
Expand Down Expand Up @@ -380,8 +448,7 @@ for (const t of model.enumerations) {

writeLine("const (");
for (const v of t.values) {
writeDocumentation(v.documentation);
writeDeprecation(v.deprecated);
writeDocumentation(v.documentation, v.proposed, v.since, v.sinceTags, v.deprecated);

write(t.name);
write(v.name);
Expand All @@ -408,8 +475,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.documentation, t.proposed, t.since, t.sinceTags, t.deprecated);

if (t.name === "LSPAny") {
writeLine("type LSPAny = any\n");
Expand Down Expand Up @@ -452,17 +518,15 @@ writeLine("}");
writeLine("// Requests");
writeLine("const (");
for (const t of model.requests) {
writeDocumentation(t.documentation);
writeDeprecation(t.deprecated);
writeDocumentation(t.documentation, t.proposed, t.since, t.sinceTags, t.deprecated);
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.documentation, t.proposed, t.since, t.sinceTags, t.deprecated);
writeLine("Method" + methodNameToIdentifier(t.method) + ' Method = "' + t.method + '"');
}
writeLine(")\n");
Expand Down
Loading