code comments and minor improvements

langserver/completions.js

@@ -6,19 +6,31 @@ const { formatDoc } = require('./doc-formatter');
 const { trace } = require('./logging');
 
 /**
- * @param {{name:string}} a 
- * @param {{name:string}} b 
+ * Case-insensitive sort routines
  */
 const sortBy = {
     label: (a,b) => a.label.localeCompare(b.label, undefined, {sensitivity: 'base'}),
     name: (a,b) => a.name.localeCompare(b.name, undefined, {sensitivity: 'base'}),
 }
 
+/** Map Java typeKind values to vscode CompletionItemKinds */
+const TypeKindMap = {
+    class: CompletionItemKind.Class,
+    interface: CompletionItemKind.Interface,
+    '@interface': CompletionItemKind.Interface,
+    enum: CompletionItemKind.Enum,
+};
+
 /**
- * @param {Map<string,CEIType>} typemap
- * @param {string} type_signature 
- * @param {{ statics: boolean }} opts 
- * @param {string[]} [typelist]
+ * Return a list of vscode-compatible completion items for a given type.
+ * 
+ * The type is located in typemap and the members (fields, methods) are retrieved
+ * and converted to completions items.
+ * 
+ * @param {Map<string,CEIType>} typemap Set of known types
+ * @param {string} type_signature Type to provide completion items for
+ * @param {{ statics: boolean }} opts used to control if static or instance members should be included
+ * @param {string[]} [typelist] optional pre-prepared type list (to save recomputing it)
  */
 function getTypedNameCompletion(typemap, type_signature, opts, typelist) {
     let type, types, subtype_search;
@@ -39,50 +51,57 @@ function getTypedNameCompletion(typemap, type_signature, opts, typelist) {
         if (!(type instanceof CEIType)) {
             return [];
         }
+        // retrieve the complete list of inherited types
         types = getTypeInheritanceList(type);
         subtype_search = type.shortSignature + '$';
     }
 
 
-    // add inner types, fields and methods
-    class FirstSetMap extends Map {
+    class SetOnceMap extends Map {
         set(key, value) {
             return this.has(key) ? this : super.set(key, value);
         }
     }
-    const fields = new FirstSetMap(), methods = new FirstSetMap();
+    const fields = new SetOnceMap(), methods = new SetOnceMap(), inner_types = new SetOnceMap();
 
     /**
      * @param {string[]} modifiers 
      * @param {JavaType} t 
      */
     function shouldInclude(modifiers, t) {
+        // filter statics/instances
         if (opts.statics !== modifiers.includes('static')) return;
         if (modifiers.includes('public')) return true;
         if (modifiers.includes('protected')) return true;
+        // only include private items for the current type
         if (modifiers.includes('private') && t === type) return true;
         // @ts-ignore
         return t.packageName === type.packageName;
     }
 
+    // retrieve fields and methods
     types.forEach((t,idx) => {
         t.fields.sort(sortBy.name)
             .filter(f => shouldInclude(f.modifiers, t))
-            .forEach(f => fields.set(f.name, {f, t, sortText: `${idx+100}${f.name}`}));
+            .forEach(f => fields.set(f.name, {f, t, sortText: `${idx+1000}${f.name}`}));
         t.methods.sort(sortBy.name)
             .filter(f => shouldInclude(f.modifiers, t))
-            .forEach(m => methods.set(`${m.name}${m.methodSignature}`, {m, t, sortText: `${idx+100}${m.name}`}));
+            .forEach(m => methods.set(`${m.name}${m.methodSignature}`, {m, t, sortText: `${idx+2000}${m.name}`}));
     });
 
-    return [
-        ...(typelist || [...typemap.keys()]).map(t => {
-            if (!opts.statics) return;
-            if (!subtype_search || !t.startsWith(subtype_search)) return;
-            return {
-                label: t.slice(subtype_search.length).replace(/\$/g,'.'),
-                kind: CompletionItemKind.Class,
+    if (opts.statics && subtype_search) {
+        // retrieve inner types
+        (typelist || [...typemap.keys()])
+            .filter(type_signature =>
+                type_signature.startsWith(subtype_search)
+                        // ignore inner-inner types
+                    && !type_signature.slice(subtype_search.length).includes('$')
+            )
+            .map(type_signature => typemap.get(type_signature))
+            .forEach((t,idx) => inner_types.set(type.simpleTypeName, { t, sortText: `${idx+3000}${t.simpleTypeName}` }));
     }
-        }).filter(x => x),
+
+    return [
         // fields
         ...[...fields.values()].map(f => ({
             label: `${f.f.name}: ${f.f.type.simpleTypeName}`,
@@ -98,18 +117,28 @@ function getTypedNameCompletion(typemap, type_signature, opts, typelist) {
             insertText: m.m.name,
             sortText: m.sortText,
             data: { type: m.t.shortSignature, midx: m.t.methods.indexOf(m.m) },
-        }))
+        })),
+        // types
+        ...[...inner_types.values()].map(it => ({
+            label: it.t.simpleTypeName,
+            kind: TypeKindMap[it.t.typeKind],
+            sortText: it.sortText,
+            data: { type: it.shortSignature },
+        })),
     ]
 }
     
 /**
- * @param {Map<string,CEIType>} typemap
+ * Return a list of vscode-compatible completion items for a dotted identifier (package or type).
+ * 
+ * @param {Map<string,CEIType>} typemap Set of known types
  * @param {string} dotted_name 
- * @param {{ statics: boolean }} opts 
+ * @param {{ statics: boolean }} opts used to control if static or instance members should be included
  */
 function getFullyQualifiedDottedIdentCompletion(typemap, dotted_name, opts) {
     if (dotted_name === '') {
-        return getPackageCompletion(typemap, '');
+        // return the list of top-level package names
+        return getTopLevelPackageCompletions(typemap);
     }
     // name is a fully dotted name, possibly including members and their fields
     let typelist = [...typemap.keys()];
@@ -150,7 +179,7 @@ function getFullyQualifiedDottedIdentCompletion(typemap, dotted_name, opts) {
                         arr.push({
                             label: m[1],
                             kind: CompletionItemKind.Unit,
-                            data: -1,
+                            data: null,
                         })
                     }
                 } else {
@@ -158,7 +187,7 @@ function getFullyQualifiedDottedIdentCompletion(typemap, dotted_name, opts) {
                     arr.push({
                         label: m[1].replace(/\$/g,'.'),
                         kind: CompletionItemKind.Class,
-                        data: -1,
+                        data: { type: typename },
                     })
                 }
             }
@@ -168,19 +197,27 @@ function getFullyQualifiedDottedIdentCompletion(typemap, dotted_name, opts) {
 }
 
 /**
+ * Return a list of completion items for top-level package names (e.g java, javax, android)
+ * 
  * @param {Map<string,CEIType>} typemap
  */
-function getRootPackageCompletions(typemap) {
-    const pkgs = [...typemap.keys()].reduce((set,typename) => {
-        const m = typename.match(/(.+?)\//);
+function getTopLevelPackageCompletions(typemap) {
+    const pkgs = [...typemap.keys()].reduce((set, short_type_signature) => {
+        // the root package is the first part of the short type signature (up to the first /)
+        const m = short_type_signature.match(/(.+?)\//);
         m && set.add(m[1]);
         return set;
     }, new Set());
-    return [...pkgs].filter(x => x).sort().map(pkg => ({
-        label: pkg,
+
+    const items = [...pkgs].filter(x => x)
+        .sort()
+        .map(package_ident => ({
+            label: package_ident,
             kind: CompletionItemKind.Unit,
-        sortText: pkg,
+            sortText: package_ident,
         }));
+
+    return items;
 }
 
 /**
@@ -189,7 +226,7 @@ function getRootPackageCompletions(typemap) {
  */
 function getPackageCompletion(typemap, pkg) {
     if (pkg === '') {
-        return getRootPackageCompletions(typemap);
+        return getTopLevelPackageCompletions(typemap);
     }
     // sub-package
     const search_pkg = pkg + '/';
@@ -204,19 +241,16 @@ function getPackageCompletion(typemap, pkg) {
     return [...pkgs].filter(x => x).sort().map(pkg => ({
         label: pkg,
         kind: CompletionItemKind.Unit,
-        data: -1,
+        data: null,
     }));
 }
 
+/** Cache of completion items for fixed values, keywords and Android library types */
 let defaultCompletionTypes = null;
+
 /** @type {Map<string,CEIType>} */
 let lastCompletionTypeMap = null;
-const typeKindMap = {
-    class: CompletionItemKind.Class,
-    interface: CompletionItemKind.Interface,
-    '@interface': CompletionItemKind.Interface,
-    enum: CompletionItemKind.Enum,
-};
+
 function initDefaultCompletionTypes(lib) {
     defaultCompletionTypes = {
         instances: 'this super'.split(' ').map(t => ({
@@ -248,42 +282,50 @@ function initDefaultCompletionTypes(lib) {
                 /** @type {CompletionItem} */
                 ({
                     label: t.dottedTypeName,
-                    kind: typeKindMap[t.typeKind],
+                    kind: TypeKindMap[t.typeKind],
                     data: { type: t.shortSignature },
                     sortText: t.dottedTypeName,
                 })
-            ).sort((a,b) => a.label.localeCompare(b.label, undefined, {sensitivity:'base'})),
-
+            ).sort(sortBy.label),
         // package names
-        packageNames: getRootPackageCompletions(lib),
+        packageNames: getTopLevelPackageCompletions(lib),
     }
 }
 
 /**
+ * Called from the VSCode completion item request.
  * 
  * @param {import('vscode-languageserver').CompletionParams} params
- * @param {*} liveParsers 
- * @param {*} androidLibrary 
+ * @param {Map<string,import('./document').JavaDocInfo>} liveParsers 
+ * @param {Map<string,CEIType>} androidLibrary 
  */
 async function getCompletionItems(params, liveParsers, androidLibrary) {
-    // The pass parameter contains the position of the text document in
-    // which code complete got requested. For the example we ignore this
-    // info and always provide the same completion items.
     trace('getCompletionItems');
+
+    if (!params || !params.textDocument || !params.textDocument.uri) {
+        return [];
+    }
+
+    if (!defaultCompletionTypes) {
+        initDefaultCompletionTypes(androidLibrary);
+    }
+
+    // wait for the Android library to load (in case we receive an early request)
     if (androidLibrary instanceof Promise) {
         androidLibrary = await androidLibrary;
     }
-    if (!params || !params.textDocument) {
-        return [];
-    }
+
+    // retrieve the parsed source corresponding to the request URI
     const docinfo = liveParsers.get(params.textDocument.uri);
     if (!docinfo || !docinfo.parsed) {
         return [];
     }
+
+    // wait for the user to stop typing
     const preversion = docinfo.version;
     await docinfo.reparseWaiter;
     if (docinfo.version !== preversion) {
-        // if the content has changed, ignore the current request
+        // if the file content has changed since this request wss made, ignore it
         trace('content changed - ignoring completion items')
         /** @type {import('vscode-languageserver').CompletionList} */
         return {
@@ -291,13 +333,21 @@ async function getCompletionItems(params, liveParsers, androidLibrary) {
             items: [],
         }
     }
+
     let parsed = docinfo.parsed;
 
+    // save the typemap associated with this parsed state - we use this when resolving
+    // the documentation later
     lastCompletionTypeMap = (parsed && parsed.typemap) || androidLibrary;
-    let locals = [], sourceTypes = [], show_instances = false;
+
+    let locals = [],
+        modifiers = defaultCompletionTypes.modifiers,
+        sourceTypes = [];
+
     if (parsed.unit) {
-        const index = indexAt(params.position, parsed.content);
-        const options = parsed.unit.getCompletionOptionsAt(index);
+        const char_index = indexAt(params.position, parsed.content);
+        const options = parsed.unit.getCompletionOptionsAt(char_index);
+        
         if (options.loc) {
             if (/^pkgname:/.test(options.loc.key)) {
                 return getPackageCompletion(parsed.typemap, options.loc.key.split(':').pop());
@@ -315,20 +365,28 @@ async function getCompletionItems(params, liveParsers, androidLibrary) {
                 return getTypedNameCompletion(parsed.typemap, options.loc.key.split(':').pop(),  { statics: false });
             }
         }
+
+        // if this token is inside a method, include the parameters and this/super
         if (options.method) {
-            show_instances = !options.method.modifiers.includes('static');
-            locals = options.method.parameters.sort(sortBy.name).map(p => ({
+            locals = options.method.parameters
+                .sort(sortBy.name)
+                .map(p => ({
                     label: p.name,
                     kind: CompletionItemKind.Variable,
                     sortText: p.name,
-            }))
+                }));
+            
+            // if this is not a static method, include this/super
+            if (!options.method.modifiers.includes('static')) {
+                locals.push(...defaultCompletionTypes.instances);
+            }
+
+            // if we're inside a method, don't show the modifiers
+            modifiers = [];
         }
     }
 
-    if (!defaultCompletionTypes) {
-        initDefaultCompletionTypes(androidLibrary);
-    }
-
+    // add types currently parsed from the source files
     liveParsers.forEach(doc => {
         if (!doc.parsed) {
             return;
@@ -336,34 +394,38 @@ async function getCompletionItems(params, liveParsers, androidLibrary) {
         doc.parsed.unit.types.forEach(
             t => sourceTypes.push({
                 label: t.dottedTypeName,
-                kind: typeKindMap[t.typeKind],
+                kind: TypeKindMap[t.typeKind],
                 data: { type:t.shortSignature },
                 sortText: t.dottedTypeName,
             })
         )
     });
 
-    return [
-        ...locals,
-        ...(show_instances ? defaultCompletionTypes.instances : []),
-        ...defaultCompletionTypes.primitiveTypes,
-        ...defaultCompletionTypes.literals,
-        ...defaultCompletionTypes.modifiers,
-        ...[
+    // exclude dotted (inner) types because they result in useless 
+    // matches in the intellisense filter when . is pressed
+    const types = [
         ...defaultCompletionTypes.types,
         ...sourceTypes,
-        ]   // exclude dotted (inner) types because they result in useless 
-            // matches in the intellisense filter when . is pressed
-            .filter(x => !x.label.includes('.'))
-            .sort(sortBy.label),
+        ].filter(x => !x.label.includes('.'))
+        .sort(sortBy.label)
+
+    return [
+        ...locals,
+        ...defaultCompletionTypes.primitiveTypes,
+        ...defaultCompletionTypes.literals,
+        ...modifiers,
+        ...types,
         ...defaultCompletionTypes.packageNames,
     ].map((x,idx) => {
-        x.sortText = `${10000+idx}-${x.label}`;
+        // to force the order above, reset sortText for each item based upon a fixed-length number
+        x.sortText = `${1000+idx}`;
         return x;
     })
 }
 
 /**
+ * Set the detail and documentation for the specified item
+ * 
  * @param {CompletionItem} item
  */
 function resolveCompletionItem(item) {
@@ -371,13 +433,13 @@ function resolveCompletionItem(item) {
     if (!lastCompletionTypeMap) {
         return item;
     }
-    if (typeof item.data !== 'object') {
+    if (!item.data || typeof item.data !== 'object') {
         return item;
     }
-    const t = lastCompletionTypeMap.get(item.data.type);
-    const field = t && t.fields[item.data.fidx];
-    const method = t && t.methods[item.data.midx];
-    if (!t) {
+    const type = lastCompletionTypeMap.get(item.data.type);
+    const field = type && type.fields[item.data.fidx];
+    const method = type && type.methods[item.data.midx];
+    if (!type) {
         return item;
     }
     let detail, documentation, header;
@@ -386,13 +448,13 @@ function resolveCompletionItem(item) {
         documentation = field.docs;
         header = `${field.type.simpleTypeName} **${field.name}**`;
     } else if (method) {
-        detail = `${method.modifiers.filter(m => !/abstract|transient|native/.test(m)).join(' ')} ${t.simpleTypeName}.${method.name}`;
+        detail = `${method.modifiers.filter(m => !/abstract|transient|native/.test(m)).join(' ')} ${type.simpleTypeName}.${method.name}`;
         documentation = method.docs;
         header = method.shortlabel.replace(/^\w+/, x => `**${x}**`).replace(/^(.+?)\s*:\s*(.+)/, (_,a,b) => `${b} ${a}`);
     } else {
-        detail = t.fullyDottedRawName,
-        documentation = t.docs,
-        header = `${t.typeKind} **${t.dottedTypeName}**`;
+        detail = type.fullyDottedRawName,
+        documentation = type.docs,
+        header = `${type.typeKind} **${type.dottedTypeName}**`;
     }
     item.detail = detail || '';
     item.documentation = formatDoc(header, documentation);

langserver/doc-formatter.js

@@ -1,16 +1,19 @@
 /**
+ * Convert JavaDoc content to markdown used by vscode.
+ * 
+ * This is a *very* rough conversion, simply looking for HTML tags and replacing them
+ * with relevant markdown characters.
+ * It is neither complete, nor perfect.
+ * 
  * @param {string} header 
  * @param {string} documentation 
  * @returns {import('vscode-languageserver').MarkupContent}
  */
 function formatDoc(header, documentation) {
-    if (!documentation) {
-        return null;
-    }
     return {
         kind: 'markdown',
         value: `${header ? header + '\n\n' : ''}${
-            documentation
+            (documentation || '')
             .replace(/(^\/\*+|(?<=\n)[ \t]*\*+\/?|\*+\/)/gm, '')
             .replace(/(\n[ \t]*@[a-z]+)|(<p(?: .*)?>)|(<\/?i>|<\/?em>)|(<\/?b>|<\/?strong>|<\/?dt>)|(<\/?tt>)|(<\/?code>|<\/?pre>|<\/?blockquote>)|(\{@link.+?\}|\{@code.+?\})|(<li>)|(<a href="\{@docRoot\}.*?">.+?<\/a>)|(<h\d>)|<\/?dd ?.*?>|<\/p ?.*?>|<\/h\d ?.*?>|<\/?div ?.*?>|<\/?[uo]l ?.*?>/gim, (_,prm,p,i,b,tt,c,lc,li,a,h) => {
                 return prm ? `  ${prm}`

langserver/document.js

@@ -11,12 +11,19 @@ const { time, timeEnd, trace } = require('./logging');
 
 /**
  * Marker to prevent early parsing of source files before we've completed our
- * initial source file load
+ * initial source file load (we cannot accurately parse individual files until we
+ * know what all the types are - hence the need to perform a first parse of all the source files).
+ * 
+ * While we are waiting for the first parse to complete, individual files-to-parse are added
+ * to this set. Once the first scan and parse is done, these are reparsed and
+ * first_parse_waiting is set to `null`.
  * @type {Set<string>}
  */
 let first_parse_waiting = new Set();
 
 /**
+ * Convert a line,character position to an absolute character offset
+ * 
  * @param {{line:number,character:number}} pos 
  * @param {string} content 
  */
@@ -32,6 +39,8 @@ function indexAt(pos, content) {
 }
 
 /**
+ * Convert an absolute character offset to a line,character position
+ * 
  * @param {number} index 
  * @param {string} content 
  */
@@ -52,20 +61,32 @@ function positionAt(index, content) {
     }
 }
 
+/**
+ * Class for storing data about Java source files
+ */
 class JavaDocInfo {
      /**
-      * @param {string} uri 
-      * @param {string} content 
-      * @param {number} version 
+      * @param {string} uri the file URI
+      * @param {string} content the full file content
+      * @param {number} version revision number for edited files (each edit increments the version)
       */
      constructor(uri, content, version) {
          this.uri = uri;
          this.content = content;
          this.version = version;
-         /** @type {ParsedInfo} */
+         /** 
+          * The result of the Java parse
+          * @type {ParsedInfo}
+          */
          this.parsed = null;
-         /** @type {Promise} */
+         
+         /**
+          * Promise linked to a timer which resolves a short time after the user stops typing
+          * - This is used to prevent constant reparsing while the user is typing in the document
+          * @type {Promise}
+          */
          this.reparseWaiter = Promise.resolve();
+
          /** @type {{ resolve: () => void, timer: * }} */
          this.waitInfo = null;
      }
@@ -79,11 +100,11 @@ class JavaDocInfo {
       * keys are typed before the timer expires, the timer is restarted.
       * Once typing pauses, the timer expires and the content reparsed.
       * 
-      * A `reparseWaiter` promise is used to delay the completion items
-      * retrieval until the reparse is complete.
+      * A `reparseWaiter` promise is used to delay actions like completion items
+      * retrieval and method signature resolving until the reparse is complete.
       * 
-      * @param {*} liveParsers 
-      * @param {*} androidLibrary 
+      * @param {Map<string,JavaDocInfo>} liveParsers 
+      * @param {Map<string,CEIType>} androidLibrary 
       */
      scheduleReparse(liveParsers, androidLibrary) {
         const createWaitTimer = () => {
@@ -112,13 +133,16 @@ class JavaDocInfo {
     }
 }
 
+/**
+ * Result from parsing a Java file
+ */
 class ParsedInfo {
     /**
-     * @param {string} uri 
-     * @param {string} content 
-     * @param {number} version 
-     * @param {Map<string,CEIType>} typemap 
-     * @param {SourceUnit} unit 
+     * @param {string} uri the file URI
+     * @param {string} content the full file content
+     * @param {number} version the version this parse applies to
+     * @param {Map<string,CEIType>} typemap the set of known types
+     * @param {SourceUnit} unit the parsed unit
      * @param {ParseProblem[]} problems 
      */
     constructor(uri, content, version, typemap, unit, problems) {
@@ -133,31 +157,35 @@ class ParsedInfo {
 
 /**
  * @param {string[]} uris
- * @param {*} liveParsers
- * @param {*} androidLibrary
+ * @param {Map<string, JavaDocInfo>} liveParsers
+ * @param {Map<string,CEIType>} androidLibrary
  * @param {{includeMethods: boolean, first_parse?: boolean}} [opts]
  */
 function reparse(uris, liveParsers, androidLibrary, opts) {
     trace(`reparse`);
+    // we must have at least one URI
     if (!uris || !uris.length) {
         return;
     }
     if (first_parse_waiting) {
         if (!opts || !opts.first_parse) {
+            // we are waiting for the first parse to complete - add this file to the list
             uris.forEach(uri => first_parse_waiting.add(uri));
             trace('waiting for first parse')
             return;
         }
     }
+
     if (androidLibrary instanceof Promise) {
-        // reparse after the library has loaded
+        // reparse after the library has finished loading
         androidLibrary.then(lib => reparse(uris, liveParsers, lib, opts));
         return;
     }
+
     const cached_units = [], parsers = [];
     for (let docinfo of liveParsers.values()) {
         if (uris.includes(docinfo.uri)) {
-            // make a copy of the content in case doc changes while we're parsing
+            // make a copy of the content + version in case the source file is edited while we're parsing
             parsers.push({uri: docinfo.uri, content: docinfo.content, version: docinfo.version});
         } else if (docinfo.parsed) {
             cached_units.push(docinfo.parsed.unit);
@@ -167,9 +195,13 @@ function reparse(uris, liveParsers, androidLibrary, opts) {
         return;
     }
 
+    // Each parse uses a unique typemap, initialised from the android library
     const typemap = new Map(androidLibrary);
+
+    // perform the parse
     const units = parse(parsers, cached_units, typemap);
 
+    // create new ParsedInfo instances for each of the parsed units
     units.forEach(unit => {
         const parser = parsers.find(p => p.uri === unit.uri);
         if (!parser) return;
@@ -180,7 +212,8 @@ function reparse(uris, liveParsers, androidLibrary, opts) {
 
     let method_body_uris = [];
     if (first_parse_waiting) {
-        // this is the first parse - parse the bodies of any waiting
+        // this is the first parse - parse the bodies of any waiting URIs and
+        // set first_parse_waiting to null
         method_body_uris = [...first_parse_waiting];
         first_parse_waiting = null;
     }
@@ -203,10 +236,11 @@ function reparse(uris, liveParsers, androidLibrary, opts) {
 }
 
 /**
- * Called during initialization and whenver the App Source Root setting is changed to scan
+ * Called during initialization and whenever the App Source Root setting is changed to scan
  * for source files
+ * 
  * @param {string} src_folder absolute path to the source root
- * @param {*} liveParsers
+ * @param {Map<string,JavaDocInfo>} liveParsers
  */
 async function rescanSourceFolders(src_folder, liveParsers) {
     if (!src_folder) {
@@ -234,7 +268,9 @@ async function rescanSourceFolders(src_folder, liveParsers) {
         }
 
         try {
+            // read the full file content
             const file_content = await new Promise((res, rej) => fs.readFile(file.fpn, 'UTF8', (err,data) => err ? rej(err) : res(data)));
+            // construct a new JavaDoc instance for the source file
             liveParsers.set(uri, new JavaDocInfo(uri, file_content, 0));
         } catch {}
     }

langserver/java/source-types.js

@@ -653,7 +653,7 @@ class SourceUnit {
             return null;
         }
         for (let type of this.types) {
-            for (let method of type.sourceMethods) {
+            for (let method of [...type.sourceMethods, ...type.constructors, ...type.initers]) {
                 if (method.body && method.body.tokens && method.body.tokens.includes(token)) {
                     return method;
                 }

langserver/logging.js

@@ -3,6 +3,7 @@ const { Settings } = require('./settings');
 const earlyTraceBuffer = [];
 
 /**
+ * Log a trace message with a timestamp - only logs if "Trace enabled" in settings
  * @param {string} s 
  */
 function trace(s) {
@@ -25,14 +26,30 @@ function info(msg) {
     console.log(msg);
 }
 
+/**
+ * Set of active timers
+ * @type {Set<string>}
+ */
+const timersRunning = new Set();
+
+/**
+ * Starts a named timer using `console.time()` - only if "Trace Enabled" in Settings
+ * @param {string} label 
+ */
 function time(label) {
     if (Settings.trace) {
+        timersRunning.add(label);
         console.time(label);
     }
 }
 
+/**
+ * Stops a named timer (and prints the elapsed time) using `console.timeEnd()`
+ * @param {string} label 
+ */
 function timeEnd(label) {
-    if (Settings.trace) {
+    if (timersRunning.has(label)) {
+        timersRunning.delete(label);
         console.timeEnd(label);
     }
 }

langserver/method-signatures.js

@@ -4,8 +4,21 @@ const { formatDoc } = require('./doc-formatter');
 const { trace } = require('./logging');
 
 /**
+ * Retrieve method signature information
+ * 
+ * Each parsed token that is relevant to a method call is 
+ * tagged with the list of possible methods and the best matched
+ * method. The tagged tokens include:
+ * - the opening bracket
+ * - each token in every argument
+ * - each comma between the arguments
+ * 
+ * The function locates the nearest non-ws token and checks
+ * for any tagged method-call info. It then converts it
+ * to the relevant vscode method signature structure for display.
+ * 
  * @param {import('vscode-languageserver').SignatureHelpParams} request
- * @param {*} liveParsers
+ * @param {Map<string,import('./document').JavaDocInfo>} liveParsers
  */
 async function getSignatureHelp(request, liveParsers) {
     trace('getSignatureHelp');
@@ -19,19 +32,27 @@ async function getSignatureHelp(request, liveParsers) {
     if (!docinfo || !docinfo.parsed) {
         return sighelp;
     }
+
+    // wait for any active edits to complete
     await docinfo.reparseWaiter;
+
+    // locate the token at the requested position
     const index = indexAt(request.position, docinfo.content);
     const token = docinfo.parsed.unit.getTokenAt(index);
     if (!token || !token.methodCallInfo) {
         trace('onSignatureHelp - no method call info');
         return sighelp;
     }
+
+    // the token has method information attached to it
+    // - convert it to the required vscode format
     trace(`onSignatureHelp - ${token.methodCallInfo.methods.length} methods`);
     sighelp = {
         signatures: token.methodCallInfo.methods.map(m => {
             const documentation = formatDoc(`#### ${m.owner.simpleTypeName}${m instanceof Method ? `.${m.name}` : ''}()`, m.docs);
             const param_docs = new Map();
             if (documentation) {
+                // extract each of the @param sections (if any)
                 for (let m, re=/@param\s+(\S+)([\d\D]+?)(?=\n\n|\n[ \t*]*@\w+|$)/g; m = re.exec(documentation.value);) {
                     param_docs.set(m[1], m[2]);
                 }