More comments

Author: pokey

src/languages/elseIfExtractor.ts

@@ -15,6 +15,12 @@ import {
  * @returns An extractor that will exctract `else if` branches
  */
 export function elseIfExtractor(): SelectionExtractor {
+  /**
+   * This extractor pulls out `if (foo) {}` from `if (foo) {} else {}`, ie it
+   * excludes any child `else` statement if it exists.  It will be used as the
+   * content range, but the removal range will want to include a leading or
+   * trailing `else` keyword if one exists.
+   */
   const contentRangeExtractor = childRangeSelector(["else_clause"], [], {
     includeUnnamedChildren: true,
   });
@@ -24,12 +30,20 @@ export function elseIfExtractor(): SelectionExtractor {
 
     const parent = node.parent;
     if (parent?.type !== "else_clause") {
+      // We have no leading `else` clause; ie we are a standalone `if`
+      // statement.  We may still have our own `else` child, but we are not
+      // ourselves a branch of a bigger `if` statement.
       const alternative = node.childForFieldName("alternative");
 
       if (alternative == null) {
+        // If we have no nested else clause, and are not part of an else clause
+        // ourself, then we don't need to remove any leading / trailing `else`
+        // keyword
         return contentRange;
       }
 
+      // Otherwise, we have no leading `else`, but we do have our own nested
+      // `else` clause, so we want to remove the leading `else` keyword
       const { selection } = contentRange;
       return {
         selection,
@@ -42,6 +56,8 @@ export function elseIfExtractor(): SelectionExtractor {
       };
     }
 
+    // If we get here, we are part of a bigger `if` statement; extend our
+    // removal range past our leading `else` keyword.
     const { selection } = contentRange;
     return {
       selection,
@@ -67,6 +83,9 @@ export function elseExtractor(ifNodeType: string): SelectionExtractor {
   const nestedElseIfExtractor = elseIfExtractor();
 
   return function (editor: TextEditor, node: SyntaxNode): SelectionWithContext {
+    // If we are an `else if` statement, then we just run `elseIfExtractor` on
+    // our nested `if` node.  Otherwise we are a simple `else` branch and don't
+    // need to do anything fancy.
     return node.namedChild(0)!.type === ifNodeType
       ? nestedElseIfExtractor(editor, node.namedChild(0)!)
       : simpleSelectionExtractor(editor, node);