Merge pull request #6 from wkillerud/feat/sassdoc-authoring

Improvements to SassDoc editing

.nvmrc

@@ -0,0 +1 @@
+16.15.0

.vscode/launch.json

@@ -2,27 +2,40 @@
 {
 	"version": "0.2.0",
 	"configurations": [
-	  {
-		"type": "extensionHost",
-		"request": "launch",
-		"name": "Launch Client",
-		"runtimeExecutable": "${execPath}",
-		"args": ["--extensionDevelopmentPath=${workspaceRoot}"],
-		"outFiles": ["${workspaceRoot}/dist/**/*.js"]
-	  },
-	  {
-		"type": "node",
-		"request": "attach",
-		"name": "Attach to Server",
-		"port": 6006,
-		"restart": true,
-		"outFiles": ["${workspaceRoot}/dist/unsafe/**/*.js"]
-	  }
+		{
+			"name": "Integration Tests",
+			"type": "extensionHost",
+			"request": "launch",
+			"runtimeExecutable": "${execPath}",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}",
+				"--extensionTestsPath=${workspaceFolder}/out/unsafe/test/e2e/suite",
+				"${workspaceFolder}/fixtures/e2e/"
+			],
+			"outFiles": ["${workspaceFolder}/out/unsafe/test/e2e/**/*.js"]
+
+		},
+		{
+			"type": "extensionHost",
+			"request": "launch",
+			"name": "Launch Client",
+			"runtimeExecutable": "${execPath}",
+			"args": ["--extensionDevelopmentPath=${workspaceRoot}"],
+			"outFiles": ["${workspaceRoot}/dist/**/*.js"]
+		},
+		{
+			"type": "node",
+			"request": "attach",
+			"name": "Attach to Server",
+			"port": 6006,
+			"restart": true,
+			"outFiles": ["${workspaceRoot}/dist/unsafe/**/*.js"]
+		}
 	],
 	"compounds": [
-	  {
-		"name": "Client + Server",
-		"configurations": ["Launch Client", "Attach to Server"]
-	  }
+		{
+			"name": "Client + Server",
+			"configurations": ["Launch Client", "Attach to Server"]
+		}
 	]
-  }
+}

.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  "somesass.scannerDepth": 30,
+  "somesass.scannerExclude": [
+    "**/.git",
+    "**/node_modules",
+    "**/bower_components"
+  ],
+  "somesass.scanImportedFiles":  true,
+  "somesass.showErrors": false,
+  "somesass.suggestAllFromOpenDocument": false,
+  "somesass.suggestFromUseOnly": false,
+  "somesass.suggestVariables": true,
+  "somesass.suggestMixins": true,
+  "somesass.suggestFunctions": true,
+  "somesass.suggestFunctionsInStringContextAfterSymbols": " (+-*%"
+}

.vscode/tasks.json

@@ -1,6 +1,11 @@
 {
 	"version": "2.0.0",
 	"tasks": [
+		{
+			"type": "npm",
+			"script": "install",
+			"group": "none"
+		},
 		{
 			"type": "npm",
 			"script": "webpack",
@@ -12,7 +17,7 @@
 		},
 		{
 			"type": "npm",
-			"script": "webpack-dev",
+			"script": "dev",
 			"isBackground": true,
 			"group": {
 				"kind": "build",

CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing
+
+Thank you for showing an interest in contributing!
+
+Before you start, please make a new Issue. I don't always make new issues for all the things I currently work on. By making a new Issue we can hopefully avoid duplicating our efforts.
+
+If you open a pull request, please **make sure to set the correct target**. This is a fork, and GitHub defaults to using the source repository as a target for pull requests. Please don't create needless noise in the upstream repository. The correct target is `wkillerud/vscode-scss` and the branch `main`.
+
+## Development environment
+
+You will need these things installed:
+
+- Node.js
+- Visual Studio Code stable
+
+To get started:
+
+- Fork this repo
+- Clone your fork
+- Open your cloned repo in Visual Studio Code
+- Run `npm install`
+- Confirm existing tests are running
+  - Run `npm test`
+  - Then run `npm run test:e2e`. This downloads VS Code Insiders and runs integration tests.
+- Finally, run `npm run dev`, or the Run Build Task command in Visual Studio Code
+
+Changes should now build automatically.
+
+To test your changes:
+
+- Go to the Run and Debug section
+- Run the Launch Client configuration
+
+A new window should open with the title `[Extension Development Host]`. In this window you can open whatever project you want to use for testing. If you don't have one you can open the folder `fixtures/e2e/` in this repo.
+
+Every time you make a change you should restart the Launch Client task.
+
+Test your changes and see if they work. If they don't, it's time to do some debugging.
+
+## Debugging
+
+Changes often don't work on the first try. To get a better idea of what's happening, let's debug the _server_ portion of the extension.
+
+In this extension there is a client part and a server part, and most of the work happens in the server part.
+
+In the Run and Debug section you should find an Attach to Server configuration. Run that. You should end up with a badge showing the number 2 on the Run and Debug section.
+
+Now you can set breakpoints to inspect what is really happening in your code. Unfortunately, at time of writing you must set these breakpoints in the _compiled output_ in `dist/unsafe/server.js`.
+
+Open `dist/unsafe/server.js`, search for a function name close to where you want to debug, and place breakpoints where you would like. Then test your changes in the Extension Development Host again. Hopefully you should see the code pause on your breakpoint. If not, confirm the Attach to Server task is running, or try to place breakpoints elsewhere. Something unexpected may stop you from reaching your code.
+
+### Debugging unit tests
+
+Unit tests can be useful tools to debug more efficiently. If you want to debug using a unit test, the same rule applies – you have to set breakpoints on the compiled output.
+
+Tests are compiled to `out/unsafe/test/`. Find your test, or the code you want to debug in the `out/unsafe/` folder, and set breakpoints.
+
+The extension Mocha Test Explorer (`hbenl.vscode-mocha-test-adapter`) is useful to launch individual tests in debug mode. Install the extension, open your unit test, and press the Debug button that should appear over your test. Hopefully you should see the code pause on your breakpoint. If not, try to place breakpoints elsewhere. Something unexpected may stop you from reaching your code.
+
+### Debugging integration tests
+
+Integration tests run in the Extension Development Host, and are more realistic than unit tests. However, sometimes they can be tricky to write. You can debug the tests temselves if you'd like.
+
+This method of debugging is **not recommended** if you want to debug the functionality itself. Instead, debug using the Client + Server configuration explained above, and perform the test manually.
+
+If you still want to debug the integration tests there are a few things to keep in mind, since tests run in this way use your main stable install of VS Code (not Insiders, like from the terminal):
+
+- You will need to install Vetur (`octref.vetur`) and Svelte for VS Code (`svelte.svelte-vscode`)
+- You **must** use default settings for Some Sass. Tip: use the included Workspace Settings.
+- To compile changes in test code, run `npm run test:compile`
+
+Again, breakpoints must be set in the compiled output. Integration tests are compiled to `out/unsafe/test/e2e/suite/`. Breakpoints can _only be set in test code_, meaning any code in the `out/unsafe/test/e2e/` folder.
+
+Now you are ready to start debugging!
+
+Breakpoints set, go to the Run and Debug and run the Integration Tests configuration. Hopefully you should see the code pause on your breakpoint. If not, try to place breakpoints elsewhere. Something unexpected may stop you from reaching your code.

README.md

@@ -19,15 +19,19 @@ If you have SCSS IntelliSense (`mrmlnc.vscode-scss`) installed you should disabl
 
 ### Code suggestions
 
-Get suggestions for variables, mixins and functions as you type.
+Get suggestions for variables, mixins, functions, and SassDoc as you type.
 
-Completions work with and without `@use` namespaces, and there is support for `@follow` [prefixes](https://sass-lang.com/documentation/at-rules/forward#adding-a-prefix) and [hiding](https://sass-lang.com/documentation/at-rules/forward#controlling-visibility).
+Completions work with and without `@use` namespaces, and there is support for `@follow` [prefixes](https://sass-lang.com/documentation/at-rules/forward#adding-a-prefix) and [hiding](https://sass-lang.com/documentation/at-rules/forward#controlling-visibility) (the latter only with `somesass.suggestOnlyFromUse` set to `true`).
 
 If you document your mixin using the `@content` [annotation from SassDoc](http://sassdoc.com/annotations/#content)
 the extension will use that information to autosuggest brackets and move focus inside the mixin contents.
 
 ![](images/suggestions-mixins.gif)
 
+Try documenting your mixins and functions with SassDoc comment blocks.
+
+![](images/suggestions-sassdoc.gif)
+
 ### Information on hover
 
 Hover over any Sass variables, mixins or functions to see more details about them.
@@ -66,7 +70,8 @@ and use the provided suggestion. This way you can keep word based suggestions if
 
 ```jsonc
 {
-  "editor.wordBasedSuggestions": false
+  "editor.wordBasedSuggestions": false,
+  "somesass.suggestOnlyFromUse": true
 }
 ```
 

fixtures/e2e/.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  "somesass.scannerDepth": 30,
+  "somesass.scannerExclude": [
+    "**/.git",
+    "**/node_modules",
+    "**/bower_components"
+  ],
+  "somesass.scanImportedFiles":  true,
+  "somesass.showErrors": false,
+  "somesass.suggestAllFromOpenDocument": false,
+  "somesass.suggestFromUseOnly": false,
+  "somesass.suggestVariables": true,
+  "somesass.suggestMixins": true,
+  "somesass.suggestFunctions": true,
+  "somesass.suggestFunctionsInStringContextAfterSymbols": " (+-*%"
+}

fixtures/e2e/completion/AppButton.svelte

@@ -1,4 +1,4 @@
-<p class="foo" />
+<p class="foo"></p>
 
 <style lang="scss">
 $color: blue;
@@ -19,4 +19,12 @@ $fonts: -apple-system;
 .foo {
   color: $;
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.
+  @include ns.
+}
+
 </style>

fixtures/e2e/completion/AppButton.vue

@@ -28,4 +28,11 @@ $fonts: -apple-system;
   color: $;
 }
 
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.
+  @include ns.
+}
+
 </style>

fixtures/e2e/completion/main.scss

@@ -16,3 +16,10 @@ $fonts: -apple-system;
 .foo {
   color: $;
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.
+  @include ns.
+}

fixtures/e2e/completion/sassdoc.scss

@@ -0,0 +1,36 @@
+@use "sass:math";
+
+///
+@mixin contentless {
+  color: limegreen;
+}
+
+///
+@mixin has-content {
+  @content;
+}
+
+///
+@mixin has-parameters($a: 1px, $b: 2px) {
+  font-size: math.calc($a + $b);
+}
+
+///
+@mixin has-parameters-and-content($a, $b) {
+  @media screen and (min-width: $a) and (max-width: #{$b - 1px}) {
+    @content;
+  }
+}
+
+///
+@function parameterless() {
+  @return 1px;
+}
+
+///
+@function parameterfull($a: 1px, $b: 2px) {
+  @return math.calc($a + $b);
+}
+
+///
+$doc-variable: 1px;

fixtures/e2e/definition/AppButton.svelte

@@ -10,4 +10,12 @@
 
   @include mixin();
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}
+
 </style>

fixtures/e2e/definition/AppButton.vue

@@ -17,4 +17,11 @@ export default {};
   @include mixin();
 }
 
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}
+
 </style>

fixtures/e2e/definition/main.scss

@@ -7,3 +7,10 @@
 
   @include mixin();
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}

fixtures/e2e/diagnostics/main.scss

@@ -10,3 +10,10 @@ $_old-private-variable: 1px;
 
   content: $_old-private-variable;
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$deprecated;
+  @include ns.mix-mix-ohno;
+}

fixtures/e2e/hover/AppButton.svelte

@@ -10,4 +10,12 @@
 
   @include mixin();
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}
+
 </style>

fixtures/e2e/hover/AppButton.vue

@@ -17,4 +17,11 @@ export default {};
   @include mixin();
 }
 
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}
+
 </style>

fixtures/e2e/hover/main.scss

@@ -7,3 +7,14 @@
 
   @include mixin();
 }
+
+@use '../namespace' as ns;
+
+.foo {
+  color: ns.$var-var-variable;
+  @include ns.mix-mix-mixin;
+}
+
+/// Some wise words
+/// @type String
+$documented-variable: 'value';