From 7faada351036c7334e365ec16c64e5b83177af8e Mon Sep 17 00:00:00 2001 From: William Killerud Date: Mon, 21 Aug 2023 20:23:43 +0200 Subject: [PATCH 1/3] Add missing SassDoc attributes to tooltips --- package-lock.json | 4 ++-- package.json | 2 +- server/src/utils/sassdoc.ts | 16 ++++++++++++++++ 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 66516d1a..a8303e62 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "some-sass", - "version": "2.14.0", + "version": "2.14.2", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "some-sass", - "version": "2.14.0", + "version": "2.14.2", "hasInstallScript": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 287f268e..2aea135f 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "some-sass", "displayName": "Some Sass: extended support for SCSS and SassDoc", "description": "Full support for @use and @forward, including aliases, prefixes and hiding. Rich documentation through SassDoc. Workspace-wide code navigation and refactoring.", - "version": "2.14.1", + "version": "2.14.2", "publisher": "SomewhatStationery", "license": "MIT", "engines": { diff --git a/server/src/utils/sassdoc.ts b/server/src/utils/sassdoc.ts index 3f850269..2ba1aaa5 100644 --- a/server/src/utils/sassdoc.ts +++ b/server/src/utils/sassdoc.ts @@ -17,6 +17,10 @@ export function applySassDoc(symbol: ScssSymbol): string { description += `\n\n@deprecated ${doc.deprecated}`; } + if (doc.name) { + description += `\n\n@name ${doc.name}`; + } + // Function and mixin parameters, listed one per line like JSDoc if (doc.parameter) { for (const parameter of doc.parameter) { @@ -38,6 +42,14 @@ export function applySassDoc(symbol: ScssSymbol): string { } } + if (doc.access) { + description += `\n\n@access ${doc.access}`; + } + + if (doc.group && doc.group.length > 0) { + description += `\n\n@group ${doc.group.join(", ")}`; + } + // Type is for standalone variable annotation // Type and Parameters is likely mutually exclusive if (doc.type) { @@ -157,5 +169,9 @@ export function applySassDoc(symbol: ScssSymbol): string { } } + if (doc.todo) { + description += `\n\n@todo ${doc.todo}`; + } + return description; } From 9156c431bc2eb84996b4cea6cae1be8d90848034 Mon Sep 17 00:00:00 2001 From: William Killerud Date: Mon, 21 Aug 2023 21:05:31 +0200 Subject: [PATCH 2/3] Add unit test for all the sassdoc --- server/src/test/utils/sassdoc.spec.ts | 197 ++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 server/src/test/utils/sassdoc.spec.ts diff --git a/server/src/test/utils/sassdoc.spec.ts b/server/src/test/utils/sassdoc.spec.ts new file mode 100644 index 00000000..9f9b0a99 --- /dev/null +++ b/server/src/test/utils/sassdoc.spec.ts @@ -0,0 +1,197 @@ +import { strictEqual } from "assert"; +import { SymbolKind } from "vscode-languageserver-types"; +import { ScssSymbol } from "../../parser"; +import { applySassDoc } from "../../utils/sassdoc"; + +describe("Utils/SassDoc", () => { + it("applySassDoc empty state", () => { + const noDoc: ScssSymbol = { + name: "test", + kind: SymbolKind.Property, + offset: 0, + position: { + character: 0, + line: 0, + }, + }; + strictEqual(applySassDoc(noDoc), ""); + }); + + it("applySassDoc maximal state", () => { + const allDocs: ScssSymbol = { + name: "test", + kind: SymbolKind.Method, + offset: 0, + position: { + character: 0, + line: 0, + }, + sassdoc: { + commentRange: { + start: 0, + end: 0, + }, + context: { + code: "test", + line: { + start: 0, + end: 0, + }, + type: "mixin", + name: "test", + scope: "global", + }, + description: "This is a description", + access: "public", + alias: "alias", + aliased: ["test", "other-test"], + author: ["Johnny Appleseed", "Foo Bar"], + content: "Overrides for test defaults", + deprecated: "No, but yes for testing", + example: [ + { + code: "@include test;", + description: "Very helpful example", + type: "scss", + }, + ], + group: ["mixins", "helpers"], + ignore: ["this", "that"], + link: [ + { + url: "http://localhost:8080", + caption: "listen!", + }, + ], + name: "Test name", + output: "Things", + parameter: [ + { + name: "parameter", + default: "yes", + description: "helpful description", + type: "string", + }, + ], + property: [ + { + path: "foo/bar", + default: "yes", + description: "what", + name: "no", + type: "number", + }, + ], + require: [ + { + name: "other-test", + type: "string", + autofill: true, + description: "helpful description", + external: true, + url: "http://localhost:1337", + }, + ], + return: { type: "string", description: "helpful result" }, + see: [ + { + name: "other-thing", + commentRange: { + start: 0, + end: 0, + }, + context: { + code: "test", + line: { + start: 0, + end: 0, + }, + type: "mixin", + name: "test", + scope: "global", + }, + description: "This is a description", + }, + ], + since: [ + { + version: "0.0.1", + description: "The beginning of time", + }, + ], + throws: ["a fit"], + todo: ["nothing"], + type: ["color", "string"], + usedBy: [ + { + name: "other-thing", + commentRange: { + start: 0, + end: 0, + }, + context: { + code: "test", + line: { + start: 0, + end: 0, + }, + type: "mixin", + name: "test", + scope: "global", + }, + description: "This is a description", + }, + ], + }, + }; + + strictEqual( + applySassDoc(allDocs), + `This is a description + +@deprecated No, but yes for testing + +@name Test name + +@param string\`parameter\` [yes] - helpful description + +@access public + +@group mixins, helpers + +@type color,string + +@prop {number}\`foo/bar\` [yes] - what + +@content Overrides for test defaults + +@output Things + +@return string - helpful result + +@throw a fit + +@require {string}\`other-test\` - helpful description http://localhost:1337 + +@alias \`alias\` + +@see \`other-thing\` + +@since 0.0.1 - The beginning of time + +@author Johnny Appleseed + +@author Foo Bar + +[listen!](http://localhost:8080) + +@example Very helpful example + +\`\`\`scss +@include test; +\`\`\` + +@todo nothing`, + ); + }); +}); From 53759fdbf48e768472c509baff1dd712fd73d47f Mon Sep 17 00:00:00 2001 From: William Killerud Date: Mon, 21 Aug 2023 21:26:16 +0200 Subject: [PATCH 3/3] Reduce noise from defaults/autofilled sassdoc - Public access is assumed unless otherwise stated. - Avoid stating the name twice. Basically, try to avoid machine-generated docs that can get noisy. --- server/src/test/utils/sassdoc.spec.ts | 72 +++++++++++++++++++++++++-- server/src/utils/sassdoc.ts | 19 +++---- 2 files changed, 77 insertions(+), 14 deletions(-) diff --git a/server/src/test/utils/sassdoc.spec.ts b/server/src/test/utils/sassdoc.spec.ts index 9f9b0a99..d44ad11f 100644 --- a/server/src/test/utils/sassdoc.spec.ts +++ b/server/src/test/utils/sassdoc.spec.ts @@ -17,7 +17,38 @@ describe("Utils/SassDoc", () => { strictEqual(applySassDoc(noDoc), ""); }); - it("applySassDoc maximal state", () => { + it("omits name if identical to symbol name", () => { + const allDocs: ScssSymbol = { + name: "test", + kind: SymbolKind.Method, + offset: 0, + position: { + character: 0, + line: 0, + }, + sassdoc: { + commentRange: { + start: 0, + end: 0, + }, + context: { + code: "test", + line: { + start: 0, + end: 0, + }, + type: "mixin", + name: "test", + scope: "global", + }, + description: "This is a description", + name: "test", + }, + }; + strictEqual(applySassDoc(allDocs), `This is a description`); + }); + + it("omits access if public, even if defined", () => { const allDocs: ScssSymbol = { name: "test", kind: SymbolKind.Method, @@ -43,6 +74,37 @@ describe("Utils/SassDoc", () => { }, description: "This is a description", access: "public", + }, + }; + strictEqual(applySassDoc(allDocs), `This is a description`); + }); + + it("applySassDoc maximal state", () => { + const allDocs: ScssSymbol = { + name: "test", + kind: SymbolKind.Method, + offset: 0, + position: { + character: 0, + line: 0, + }, + sassdoc: { + commentRange: { + start: 0, + end: 0, + }, + context: { + code: "test", + line: { + start: 0, + end: 0, + }, + type: "mixin", + name: "test", + scope: "global", + }, + description: "This is a description", + access: "private", alias: "alias", aliased: ["test", "other-test"], author: ["Johnny Appleseed", "Foo Bar"], @@ -155,10 +217,6 @@ describe("Utils/SassDoc", () => { @param string\`parameter\` [yes] - helpful description -@access public - -@group mixins, helpers - @type color,string @prop {number}\`foo/bar\` [yes] - what @@ -191,6 +249,10 @@ describe("Utils/SassDoc", () => { @include test; \`\`\` +@access private + +@group mixins, helpers + @todo nothing`, ); }); diff --git a/server/src/utils/sassdoc.ts b/server/src/utils/sassdoc.ts index 2ba1aaa5..5689e2a8 100644 --- a/server/src/utils/sassdoc.ts +++ b/server/src/utils/sassdoc.ts @@ -17,7 +17,7 @@ export function applySassDoc(symbol: ScssSymbol): string { description += `\n\n@deprecated ${doc.deprecated}`; } - if (doc.name) { + if (doc.name && doc.name !== symbol.name) { description += `\n\n@name ${doc.name}`; } @@ -42,14 +42,6 @@ export function applySassDoc(symbol: ScssSymbol): string { } } - if (doc.access) { - description += `\n\n@access ${doc.access}`; - } - - if (doc.group && doc.group.length > 0) { - description += `\n\n@group ${doc.group.join(", ")}`; - } - // Type is for standalone variable annotation // Type and Parameters is likely mutually exclusive if (doc.type) { @@ -169,6 +161,15 @@ export function applySassDoc(symbol: ScssSymbol): string { } } + if (doc.access === "private") { + description += `\n\n@access private`; + } + + const groups = doc.group?.filter((g) => g !== "undefined"); + if (groups && groups.length > 0) { + description += `\n\n@group ${groups.join(", ")}`; + } + if (doc.todo) { description += `\n\n@todo ${doc.todo}`; }