Added documentation for types

Author: mug1wara26

server/src/ast.ts

@@ -136,8 +136,8 @@ export class AST {
             if (specifier.imported.type === "Identifier") {
               const real_name = specifier.imported.name;
               const name = specifier.local.name;
-              let imported: Documentation | undefined;
-              if ((imported = getImportedName(module_name, real_name)) !== undefined) {
+              let imported: Documentation | undefined = getImportedName(module_name, real_name);
+              if (imported !== undefined) {
                 this.imported_names[module_name].set(real_name, { range: sourceLocToRange(specifier.loc!), local: name });
                 const declaration: ImportedSymbol = {
                   name: name,
@@ -474,6 +474,7 @@ export class AST {
               data: { type: AUTOCOMPLETE_TYPES.SYMBOL, ...item.data }
             };
           }
+          // Check if last import specifier exists after prepend, if so allow insert there
           else if ([...map][map.size-1][1].range.start.line >= this.prependLines){
             return {
               ...item,
@@ -483,6 +484,7 @@ export class AST {
             };
           };
         }
+        // Default case, insert at the first line after prepend
         return {
           ...item,
           additionalTextEdits: [

server/src/types.ts

@@ -1,12 +1,14 @@
 import { Range } from "vscode-languageserver/node";
 import * as es from 'estree';
 
-// Note that the order the enum fields appear in determine the order they are displayed in the autocomplete list
+/** 
+ * Enum for differentiating between types of autocomplete, and also used for sorting the autocomplete items within the autocomplete list
+*/
 export enum AUTOCOMPLETE_TYPES {
-	BUILTIN,
+    BUILTIN,
     KEYWORD,
-	SYMBOL,
-	MODULE
+    SYMBOL,
+    MODULE
 }
 
 export enum NODES {
@@ -46,55 +48,141 @@ export enum EXPRESSIONS {
     LAMBDA = "ArrowFunctionExpression"
 }
 
+/**
+ * Stores information about how that symbol was declared
+ */
 export interface DeclarationSymbol {
+    /**
+     * Name of the symbol, taken from the identifier
+     */
     name: string,
+    /**
+     * Scope where the symbol can be used
+     * Defined as a SourceLocation object, which has 1-index lines
+     */
     scope: es.SourceLocation,
+    /**
+     * Meta information about the declaration
+     * If a constant is declared with a lambda, it will be assigned func
+     * If a let is declared with a lambda, it will still be assigned let as it can be reassigned later on
+     */
     meta: "const" | "let" | "func",
+    /**
+     * More meta information about the declaration
+     * Has some overlap with `meta`, could be combined in the future
+     */
     declarationKind: DeclarationKind,
+    /**
+     * Range used only for highlighting purposes in DocumentSymbols, not really used anywhere else
+     */
     range: Range,
+    /**
+     * Range representing the location for the identifier of this symbol.
+     */
     selectionRange: Range,
+    /**
+     * Used for functions and lambdas to process child symbols in DocumentSymbols
+     */
     parameters?: Array<ParameterSymbol>,
+    /**
+     * Flag whether to show this symbol in DocumentSymbols
+     * As of now, only lambda and function params have this flag set to true, as they are already in the children of the function symbol
+     */
     showInDocumentSymbols?: boolean;
+    /**
+     * Flags whether this symbol has been used or not.
+     * Default should be set to true, then when an identifier for this declaration is found, flag can be set to false
+     * Right now this check occurs in the identifierRule when parsing for error diagnostics
+     */
     unused: boolean
 }
 
 export interface ParameterSymbol extends DeclarationSymbol {
+    /**
+     * Flag for whether this symbol is a rest element or not. Used for some diagnostics.
+     */
     isRestElement: boolean
 }
 
 export interface ImportedSymbol extends DeclarationSymbol {
+    /**
+     * String representing the module name where this symbol was imported from
+     */
     module_name: string,
+    /**
+     * String representing the actual defined name of this symbol in the module
+     * This should be ImportSpecifier.imported.name
+     * Not to be confused with ImportedSpecifier.local.name, which is the name for the DocumentSymbol this inherits from
+     */
     real_name: string
 }
 
+/**
+ * Represents documentation scraped from Source Academy docs
+ */
 export interface Documentation {
+    /**
+     * The name of the function/constant
+     */
     label: string,
+    /**
+     * Title of the description for the documentation
+     */
     title: string,
+    /**
+     * The whole description of this documentation
+     */
     description: string,
+    /**
+     * Meta information whether this is a constant or a function
+     */
     meta: "const" | "func",
+    /**
+     * String array of parameters if this is a function
+     */
     parameters?: string[],
+    /**
+     * Strings for names of optional parameters
+     */
     optional_params?: string[],
-    hasRestElement? : boolean
+    /**
+     * Flag whether the last parameter is a rest element
+     * If so the function can take in any amount of parameters after the last one
+     */
+    hasRestElement?: boolean
 }
 
+/**
+ * Interface for data to be stored within CompletionItems
+ */
 export interface CompletionItemData {
+    /**
+     * Type of autocomplete
+     */
     type: AUTOCOMPLETE_TYPES,
-    idx: number
+    /**
+     * Module name if AutoComplete comes from a Module, used for generating auto imports
+     */
     module_name?: string,
+    /**
+     * String array if autocomplete is a function, used for generating autocomplete parameter snippets
+     */
     parameters?: string[],
-    optional_params?: string[],
-    hasRestElement?: boolean
+    /**
+     * String array of optional parameters, used to ignore parameters in autocomplete snippet
+     */
+    optional_params?: string[]
 }
 
 
 // Taken from js-slang
 export enum DeclarationKind {
-  KIND_IMPORT = 'import',
-  KIND_FUNCTION = 'func',
-  KIND_LET = 'let',
-  KIND_PARAM = 'param',
-  KIND_CONST = 'const',
-  KIND_KEYWORD = 'keyword'
+    KIND_IMPORT = 'import',
+    KIND_FUNCTION = 'func',
+    KIND_LET = 'let',
+    KIND_PARAM = 'param',
+    KIND_CONST = 'const',
+    KIND_KEYWORD = 'keyword'
 }
 
 export enum Chapter {
@@ -104,7 +192,16 @@ export enum Chapter {
     SOURCE_4 = 4,
 }
 
+/**
+ * Context for the file being edited
+ */
 export interface Context {
+    /**
+     * Source chapter for this file
+     */
     chapter: Chapter,
+    /**
+     * Number of lines of text being prepended to the file
+     */
     prepend?: number
 }

server/src/utils.ts

@@ -18,7 +18,7 @@ export const autocomplete_labels = source.map(version => version.map((doc, idx):
       value: doc.description
     },
     kind: doc.meta === "const" ? CompletionItemKind.Constant : CompletionItemKind.Function,
-    data: { type: AUTOCOMPLETE_TYPES.BUILTIN, idx: idx, parameters: doc.parameters, optional_params: doc.optional_params, hasRestElement: doc.hasRestElement } as CompletionItemData,
+    data: { type: AUTOCOMPLETE_TYPES.BUILTIN, parameters: doc.parameters, optional_params: doc.optional_params } as CompletionItemData,
     sortText: '' + AUTOCOMPLETE_TYPES.BUILTIN
   };
 }));
@@ -39,7 +39,7 @@ for (const key in modules) {
       },
       kind: doc.meta === "const" ? CompletionItemKind.Constant : CompletionItemKind.Function,
       // @ts-ignore
-      data: { type: AUTOCOMPLETE_TYPES.MODULE, idx: idx, module_name: key, parameters: doc.parameters, optional_params: doc.optional_params } as CompletionItemData,
+      data: { type: AUTOCOMPLETE_TYPES.MODULE, module_name: key, parameters: doc.parameters, optional_params: doc.optional_params } as CompletionItemData,
       sortText: '' + AUTOCOMPLETE_TYPES.MODULE
     });
   });