From 9fde7bcd9d6dd876d7b5d749e45095778621fa0e Mon Sep 17 00:00:00 2001 From: Dave Holoway Date: Tue, 30 Jun 2020 12:07:01 +0100 Subject: [PATCH] code comments and minor improvements --- langserver/completions.js | 238 ++++++++++++++++++++------------ langserver/doc-formatter.js | 11 +- langserver/document.js | 80 ++++++++--- langserver/java/source-types.js | 2 +- langserver/logging.js | 19 ++- langserver/method-signatures.js | 23 ++- 6 files changed, 256 insertions(+), 117 deletions(-) diff --git a/langserver/completions.js b/langserver/completions.js index 14e1277..8d9fc7e 100644 --- a/langserver/completions.js +++ b/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} 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} 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}`})); }); + 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}` })); + } + 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, - } - }).filter(x => x), // 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} typemap + * Return a list of vscode-compatible completion items for a dotted identifier (package or type). + * + * @param {Map} 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} 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, - kind: CompletionItemKind.Unit, - sortText: pkg, - })); + + const items = [...pkgs].filter(x => x) + .sort() + .map(package_ident => ({ + label: package_ident, + kind: CompletionItemKind.Unit, + 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} */ 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], - data: { type:t.shortSignature }, + 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} liveParsers + * @param {Map} 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 => ({ - label: p.name, - kind: CompletionItemKind.Variable, - sortText: p.name, - })) + 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, }) ) }); + // exclude dotted (inner) types because they result in useless + // matches in the intellisense filter when . is pressed + const types = [ + ...defaultCompletionTypes.types, + ...sourceTypes, + ].filter(x => !x.label.includes('.')) + .sort(sortBy.label) + return [ ...locals, - ...(show_instances ? defaultCompletionTypes.instances : []), ...defaultCompletionTypes.primitiveTypes, ...defaultCompletionTypes.literals, - ...defaultCompletionTypes.modifiers, - ...[ - ...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), + ...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); diff --git a/langserver/doc-formatter.js b/langserver/doc-formatter.js index 7e72b69..846a845 100644 --- a/langserver/doc-formatter.js +++ b/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]+)|()|(<\/?i>|<\/?em>)|(<\/?b>|<\/?strong>|<\/?dt>)|(<\/?tt>)|(<\/?code>|<\/?pre>|<\/?blockquote>)|(\{@link.+?\}|\{@code.+?\})|(
  • )|(.+?<\/a>)|()|<\/?dd ?.*?>|<\/p ?.*?>|<\/h\d ?.*?>|<\/?div ?.*?>|<\/?[uo]l ?.*?>/gim, (_,prm,p,i,b,tt,c,lc,li,a,h) => { return prm ? ` ${prm}` diff --git a/langserver/document.js b/langserver/document.js index 431bede..f3ea488 100644 --- a/langserver/document.js +++ b/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} */ 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} liveParsers + * @param {Map} 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} 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} 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} liveParsers + * @param {Map} 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} 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 {} } diff --git a/langserver/java/source-types.js b/langserver/java/source-types.js index 1519e03..fe07518 100644 --- a/langserver/java/source-types.js +++ b/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; } diff --git a/langserver/logging.js b/langserver/logging.js index 7379f3b..850874d 100644 --- a/langserver/logging.js +++ b/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} + */ +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); } } diff --git a/langserver/method-signatures.js b/langserver/method-signatures.js index 479bcfe..2e888c5 100644 --- a/langserver/method-signatures.js +++ b/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} 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]); }