Documentation

Author: kddnewton

package.json

@@ -60,7 +60,7 @@
         },
         "syntaxTree.trailingComma": {
           "default": false,
-          "markdownDescription": "Adds an extra comma after the last item of arrays, hashes and parameters.",
+          "markdownDescription": "Adds a trailing comma to multi-line array literals, hash literals, and method parameters.",
           "type": "boolean"
         },
         "syntaxTree.additionalPlugins": {

src/extension.ts

@@ -1,6 +1,6 @@
 "use strict";
 
-import { ConfigurationChangeEvent, ExtensionContext, commands, window, workspace } from "vscode";
+import { ExtensionContext, commands, window, workspace } from "vscode";
 import { LanguageClient, ServerOptions } from "vscode-languageclient/node";
 import { promisify } from "util";
 import { exec } from "child_process";
@@ -10,49 +10,85 @@ import Visualize from "./Visualize";
 
 const promiseExec = promisify(exec);
 
+// This is the expected top-level export that is called by VSCode.
 export function activate(context: ExtensionContext) {
+  // This output channel is going to contain all of our informational messages.
+  // It's not really meant for the end-user, it's more for debugging.
   const outputChannel = window.createOutputChannel("Syntax Tree");
+
+  // These objects will get initialized once the language client is ready.
   let languageClient: LanguageClient | null = null;
   let visualizer: Visualize | null = null;
 
+  // This is the list of objects that implement the Disposable interface. They
+  // will all get cleaned up with this extension is deactivated. It's important
+  // to add them to this list so we don't leak memory.
   context.subscriptions.push(
+    // The output channel itself is a disposable. When the extension is
+    // deactivated it will be removed from the list.
     outputChannel,
+
+    // Each of the commands that interacts with this extension is a disposable.
+    // It's important to register them here as opposed to whenever the client
+    // starts up because we don't want to register them again whenever the
+    // client restarts.
     commands.registerCommand("syntaxTree.start", startLanguageServer),
     commands.registerCommand("syntaxTree.stop", stopLanguageServer),
     commands.registerCommand("syntaxTree.restart", restartLanguageServer),
     commands.registerCommand("syntaxTree.visualize", () => visualizer?.visualize()),
     commands.registerCommand("syntaxTree.showOutputChannel", () => outputChannel.show()),
-    workspace.onDidChangeConfiguration(event =>
-      event.affectsConfiguration("syntaxTree") &&
-      restartLanguageServer())
+    workspace.onDidChangeConfiguration(event => {
+      if (event.affectsConfiguration("syntaxTree")) {
+        restartLanguageServer();
+      }
+    })
   );
 
+  // We're returning a Promise from this function that will start the Ruby
+  // subprocess.
   return startLanguageServer();
 
+  // This function is called when the extension is activated or when the
+  // language server is restarted.
   async function startLanguageServer() {
+    // The top-level configuration group is syntaxTree. All of the configuration
+    // for the extension is under that group.
     const config = workspace.getConfiguration("syntaxTree");
-    const addlPlugins = config.get<string[]>("additionalPlugins") || [];
-    const singleQuotes = config.get<boolean>("singleQuotes");
-    const trailingComma = config.get<boolean>("trailingComma");
 
+    // The args are going to be passed to the stree executable. It's important
+    // that it lines up with what the CLI expects.
     const args = ["lsp"];
-
     const plugins = new Set<string>();
-    if (singleQuotes) {
+
+    if (config.get<boolean>("singleQuotes")) {
       plugins.add("plugin/single_quotes");
     }
-    if (trailingComma) {
+
+    if (config.get<boolean>("trailingComma")) {
       plugins.add("plugin/trailing_comma");
     }
-    addlPlugins.forEach(plugins.add);
 
-    if (plugins.size) {
+    const additionalPlugins = config.get<string[]>("additionalPlugins");
+    if (additionalPlugins) {
+      additionalPlugins.forEach(plugin => plugins.add(plugin));
+    }
+
+    // If there are any plugins, then we'll pass the --plugins command line
+    // option to the stree lsp command.
+    if (plugins.size > 0) {
       args.push(`--plugins=${Array.from(plugins).join(",")}`);
     }
 
     outputChannel.appendLine(`Starting language server with ${plugins.size} plugin(s)...`);
     let run: ServerOptions = { command: "stree", args };
 
+    // There's a bit of complexity here. Basically, if there's an open folder,
+    // then w're going to check if the syntax_tree gem is inside the bundle. If
+    // it is, then we'll run bundle exec stree. This is good, because it'll
+    // ensure that we get the correct version of the gem. If it's not in the
+    // bundle or there is no bundle, then we'll just run the global stree. This
+    // might be correct in the end if the right environment variables are set,
+    // but it's a bit of a prayer.
     if (workspace.workspaceFolders) {
       const cwd = workspace.workspaceFolders![0].uri.fsPath;
 
@@ -64,30 +100,42 @@ export function activate(context: ExtensionContext) {
       }
     }
 
+    // Here, we instantiate the language client. This is the object that is
+    // responsible for the communication and management of the Ruby subprocess.
     languageClient = new LanguageClient("Syntax Tree", { run, debug: run }, {
       documentSelector: [
         { scheme: "file", language: "ruby" },
       ],
       outputChannel
     });
 
+    // Here we're going to wait for the language server to start.
     context.subscriptions.push(languageClient.start());
     await languageClient.onReady();
 
+    // Finally, now that the language server has been properly started, we can
+    // add the various features to the extension. Each of them in turn
+    // implements Disposable so that they clean up their own resources.
     visualizer = new Visualize(languageClient, outputChannel);
     context.subscriptions.push(
       new InlayHints(languageClient, outputChannel),
       visualizer
     );
   }
 
+  // This function is called as part of the shutdown or restart process. It's
+  // always user-initiated either through manually executing an action or
+  // changing some configuration.
   async function stopLanguageServer() {
     if (languageClient) {
       outputChannel.appendLine("Stopping language server...");
       await languageClient.stop();
     }
   }
 
+  // This function is called as part of the restart process. Like
+  // stopLanguageServer, it's always user-initiated either through manually
+  // executing an action or changing some configuration.
   async function restartLanguageServer() {
     outputChannel.appendLine("Restarting language server...");
     await stopLanguageServer();