Alignment of default classes to interface definitions (#1604)

snarkipus · web-flow · commit 48e67d67e051 · 2024-08-14T14:38:24.000+02:00
diff --git a/packages/langium/src/lsp/completion/completion-provider.ts b/packages/langium/src/lsp/completion/completion-provider.ts
@@ -107,6 +107,10 @@ export interface CompletionProvider {
     /**
      * Handle a completion request.
      *
+     * @param document - the document for which the completion request was triggered
+     * @param params - the completion parameters
+     * @param cancelToken - a token that can be used to cancel the request
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -131,6 +135,7 @@ export class DefaultCompletionProvider implements CompletionProvider {
     protected readonly fuzzyMatcher: FuzzyMatcher;
     protected readonly grammarConfig: GrammarConfig;
     protected readonly astReflection: AstReflection;
+    readonly completionOptions?: CompletionProviderOptions;
 
     constructor(services: LangiumServices) {
         this.scopeProvider = services.references.ScopeProvider;
@@ -145,7 +150,7 @@ export class DefaultCompletionProvider implements CompletionProvider {
         this.documentationProvider = services.documentation.DocumentationProvider;
     }
 
-    async getCompletion(document: LangiumDocument, params: CompletionParams): Promise<CompletionList | undefined> {
+    async getCompletion(document: LangiumDocument, params: CompletionParams, _cancelToken?: CancellationToken): Promise<CompletionList | undefined> {
         const items: CompletionItem[] = [];
         const contexts = this.buildContexts(document, params.position);
 
diff --git a/packages/langium/src/lsp/definition-provider.ts b/packages/langium/src/lsp/definition-provider.ts
@@ -24,6 +24,11 @@ export interface DefinitionProvider {
     /**
      * Handle a go to definition request.
      *
+     * @param document The document in which the request was triggered.
+     * @param params The parameters of the request.
+     * @param cancelToken A cancellation token that can be used to cancel the request.
+     * @returns A list of location links to the definition(s) of the symbol at the given position.
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -48,7 +53,7 @@ export class DefaultDefinitionProvider implements DefinitionProvider {
         this.grammarConfig = services.parser.GrammarConfig;
     }
 
-    getDefinition(document: LangiumDocument, params: DefinitionParams): MaybePromise<LocationLink[] | undefined> {
+    getDefinition(document: LangiumDocument, params: DefinitionParams, _cancelToken?: CancellationToken): MaybePromise<LocationLink[] | undefined> {
         const rootNode = document.parseResult.value;
         if (rootNode.$cstNode) {
             const cst = rootNode.$cstNode;
diff --git a/packages/langium/src/lsp/document-highlight-provider.ts b/packages/langium/src/lsp/document-highlight-provider.ts
@@ -25,6 +25,10 @@ export interface DocumentHighlightProvider {
     /**
      * Handle a document highlight request.
      *
+     * @param document The document in which the request was received.
+     * @param params The parameters of the document highlight request.
+     * @param cancelToken A cancellation token that can be used to cancel the request.
+     * @returns The document highlights or `undefined` if no highlights are available.
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -42,7 +46,7 @@ export class DefaultDocumentHighlightProvider implements DocumentHighlightProvid
         this.grammarConfig = services.parser.GrammarConfig;
     }
 
-    getDocumentHighlight(document: LangiumDocument, params: DocumentHighlightParams): MaybePromise<DocumentHighlight[] | undefined> {
+    getDocumentHighlight(document: LangiumDocument, params: DocumentHighlightParams, _cancelToken?: CancellationToken): MaybePromise<DocumentHighlight[] | undefined> {
         const rootNode = document.parseResult.value.$cstNode;
         if (!rootNode) {
             return undefined;
diff --git a/packages/langium/src/lsp/document-symbol-provider.ts b/packages/langium/src/lsp/document-symbol-provider.ts
@@ -21,6 +21,11 @@ export interface DocumentSymbolProvider {
     /**
      * Handle a document symbols request.
      *
+     * @param document The document in the workspace.
+     * @param params The parameters of the request.
+     * @param cancelToken A cancellation token that migh be used to cancel the request.
+     * @returns The symbols for the given document.
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -37,7 +42,7 @@ export class DefaultDocumentSymbolProvider implements DocumentSymbolProvider {
         this.nodeKindProvider = services.shared.lsp.NodeKindProvider;
     }
 
-    getSymbols(document: LangiumDocument): MaybePromise<DocumentSymbol[]> {
+    getSymbols(document: LangiumDocument, _params: DocumentSymbolParams, _cancelToken?: CancellationToken): MaybePromise<DocumentSymbol[]> {
         return this.getSymbol(document, document.parseResult.value);
     }
 
diff --git a/packages/langium/src/lsp/document-update-handler.ts b/packages/langium/src/lsp/document-update-handler.ts
@@ -21,23 +21,46 @@ import type { MaybePromise } from '../utils/promise-utils.js';
  */
 export interface DocumentUpdateHandler {
 
+    /**
+     * A document open event was triggered by the `TextDocuments` service.
+     * @param event The document change event.
+     */
     didOpenDocument?(event: TextDocumentChangeEvent<TextDocument>): void;
 
     /**
      * A content change event was triggered by the `TextDocuments` service.
+     * @param event The document change event.
      */
     didChangeContent?(event: TextDocumentChangeEvent<TextDocument>): void;
 
+    /**
+     * A document save event (initiated) was triggered by the `TextDocuments` service.
+     * @param event The document change event.
+     */
     willSaveDocument?(event: TextDocumentWillSaveEvent<TextDocument>): void;
 
+    /**
+     * A document save event (initiated) was triggered by the `TextDocuments` service.
+     * @param event The document change event.
+     * @returns An array of text edits which will be applied to the document before it is saved.
+     */
     willSaveDocumentWaitUntil?(event: TextDocumentWillSaveEvent<TextDocument>): MaybePromise<TextEdit[]>;
 
+    /**
+     * A document save event (completed) was triggered by the `TextDocuments` service.
+     * @param event The document change event.
+     */
     didSaveDocument?(event: TextDocumentChangeEvent<TextDocument>): void;
 
+    /**
+     * A document close event was triggered by the `TextDocuments` service.
+     * @param event The document change event.
+     */
     didCloseDocument?(event: TextDocumentChangeEvent<TextDocument>): void;
 
     /**
      * The client detected changes to files and folders watched by the language client.
+     * @param params The files/folders change event.
      */
     didChangeWatchedFiles?(params: DidChangeWatchedFilesParams): void;
 
@@ -118,5 +141,4 @@ export class DefaultDocumentUpdateHandler implements DocumentUpdateHandler {
             .toArray();
         this.fireDocumentUpdate(changedUris, deletedUris);
     }
-
 }
diff --git a/packages/langium/src/lsp/folding-range-provider.ts b/packages/langium/src/lsp/folding-range-provider.ts
@@ -21,6 +21,11 @@ export interface FoldingRangeProvider {
     /**
      * Handle a folding range request.
      *
+     * @param document The document to compute folding ranges for
+     * @param params The folding range parameters
+     * @param cancelToken A cancellation token that can be used to cancel the request
+     * @returns The computed folding ranges
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -37,7 +42,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider {
         this.commentNames = services.parser.GrammarConfig.multilineCommentRules;
     }
 
-    getFoldingRanges(document: LangiumDocument): MaybePromise<FoldingRange[]> {
+    getFoldingRanges(document: LangiumDocument, _params: FoldingRangeParams, _cancelToken?: CancellationToken): MaybePromise<FoldingRange[]> {
         const foldings: FoldingRange[] = [];
         const acceptor: FoldingRangeAcceptor = (foldingRange) => foldings.push(foldingRange);
         this.collectFolding(document, acceptor);
@@ -73,8 +78,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider {
      * Returns true by default for all nodes. Returning false only ignores the specified node and not its content.
      * To ignore the content of a node use `shouldProcessContent`.
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    protected shouldProcess(node: AstNode): boolean {
+    protected shouldProcess(_node: AstNode): boolean {
         return true;
     }
 
@@ -83,8 +87,7 @@ export class DefaultFoldingRangeProvider implements FoldingRangeProvider {
      * Returns true by default for all nodes. Returning false ignores _all_ content of this node, even transitive ones.
      * For more precise control over foldings use the `shouldProcess` method.
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    protected shouldProcessContent(node: AstNode): boolean {
+    protected shouldProcessContent(_node: AstNode): boolean {
         return true;
     }
 
diff --git a/packages/langium/src/lsp/references-provider.ts b/packages/langium/src/lsp/references-provider.ts
@@ -23,6 +23,11 @@ export interface ReferencesProvider {
     /**
      * Handle a find references request.
      *
+     * @param document The document in which to search for references.
+     * @param params The parameters of the find references request.
+     * @param cancelToken A cancellation token that can be used to cancel the request.
+     * @returns The locations of the references.
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -40,7 +45,7 @@ export class DefaultReferencesProvider implements ReferencesProvider {
         this.grammarConfig = services.parser.GrammarConfig;
     }
 
-    findReferences(document: LangiumDocument, params: ReferenceParams): MaybePromise<Location[]> {
+    findReferences(document: LangiumDocument, params: ReferenceParams, _cancelToken?: CancellationToken): MaybePromise<Location[]> {
         const rootNode = document.parseResult.value.$cstNode;
         if (!rootNode) {
             return [];
diff --git a/packages/langium/src/lsp/rename-provider.ts b/packages/langium/src/lsp/rename-provider.ts
@@ -24,6 +24,11 @@ export interface RenameProvider {
     /**
      * Handle a rename request.
      *
+     * @param document The document in which the rename request was triggered.
+     * @param params The rename parameters.
+     * @param cancelToken A cancellation token that can be used to cancel the request.
+     * @returns A workspace edit that describes the changes to be applied to the workspace.
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -32,6 +37,11 @@ export interface RenameProvider {
     /**
      * Handle a prepare rename request.
      *
+     * @param document The document in which the prepare rename request was triggered.
+     * @param params The prepare rename parameters.
+     * @param cancelToken A cancellation token that can be used to cancel the request.
+     * @returns A range that describes the range of the symbol to be renamed.
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
@@ -50,7 +60,7 @@ export class DefaultRenameProvider implements RenameProvider {
         this.grammarConfig = services.parser.GrammarConfig;
     }
 
-    async rename(document: LangiumDocument, params: RenameParams): Promise<WorkspaceEdit | undefined> {
+    async rename(document: LangiumDocument, params: RenameParams, _cancelToken?: CancellationToken): Promise<WorkspaceEdit | undefined> {
         const changes: Record<string, TextEdit[]> = {};
         const rootNode = document.parseResult.value.$cstNode;
         if (!rootNode) return undefined;
@@ -73,7 +83,7 @@ export class DefaultRenameProvider implements RenameProvider {
         return { changes };
     }
 
-    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams): MaybePromise<Range | undefined> {
+    prepareRename(document: LangiumDocument, params: TextDocumentPositionParams, _cancelToken?: CancellationToken): MaybePromise<Range | undefined> {
         return this.renameNodeRange(document, params.position);
     }
 
diff --git a/packages/langium/src/lsp/workspace-symbol-provider.ts b/packages/langium/src/lsp/workspace-symbol-provider.ts
@@ -21,13 +21,21 @@ export interface WorkspaceSymbolProvider {
     /**
      * Handle a workspace symbols request.
      *
+     * @param params workspaces symbols request parameters
+     * @param cancelToken a cancellation token tha can be used to cancel the request
+     * @returns a list of workspace symbols
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
     getSymbols(params: WorkspaceSymbolParams, cancelToken?: CancellationToken): MaybePromise<WorkspaceSymbol[]>;
     /**
      * Handle a resolve request for a workspace symbol.
      *
+     * @param symbol the workspace symbol to resolve
+     * @param cancelToken a cancellation token tha can be used to cancel the request
+     * @returns the resolved workspace symbol
+     *
      * @throws `OperationCancelled` if cancellation is detected during execution
      * @throws `ResponseError` if an error is detected that should be sent as response to the client
      */
diff --git a/packages/langium/src/parser/async-parser.ts b/packages/langium/src/parser/async-parser.ts
@@ -14,20 +14,28 @@ import { Deferred, OperationCancelled } from '../utils/promise-utils.js';
 import { Emitter } from '../utils/event.js';
 
 /**
- * Async parser that allows to cancel the current parsing process.
- * The sync parser implementation is blocking the event loop, which can become quite problematic for large files.
+ * Async parser that allows cancellation of the current parsing process.
  *
- * Note that the default implementation is not actually async. It just wraps the sync parser in a promise.
- * A real implementation would create worker threads or web workers to offload the parsing work.
+ * @remark The sync parser implementation is blocking the event loop, which can become quite problematic for large files.
+ * @remark The default implementation is not actually async. It just wraps the sync parser in a promise. A real implementation would create worker threads or web workers to offload the parsing work.
  */
 export interface AsyncParser {
+    /**
+     * Parses the given text and returns the parse result.
+     *
+     * @param text The text to parse.
+     * @param cancelToken A cancellation token that can be used to cancel the parsing process.
+     * @returns A promise that resolves to the parse result.
+     *
+     * @throw `OperationCancelled` if the parsing process is cancelled.
+     */
     parse<T extends AstNode>(text: string, cancelToken: CancellationToken): Promise<ParseResult<T>>;
 }
 
 /**
- * Default implementation of the async parser. This implementation only wraps the sync parser in a promise.
+ * Default implementation of the async parser which simply wraps the sync parser in a promise.
  *
- * A real implementation would create worker threads or web workers to offload the parsing work.
+ * @remark A real implementation would create worker threads or web workers to offload the parsing work.
  */
 export class DefaultAsyncParser implements AsyncParser {
 
@@ -37,7 +45,7 @@ export class DefaultAsyncParser implements AsyncParser {
         this.syncParser = services.parser.LangiumParser;
     }
 
-    parse<T extends AstNode>(text: string): Promise<ParseResult<T>> {
+    parse<T extends AstNode>(text: string, _cancelToken: CancellationToken): Promise<ParseResult<T>> {
         return Promise.resolve(this.syncParser.parse<T>(text));
     }
 }
diff --git a/packages/langium/src/references/linker.ts b/packages/langium/src/references/linker.ts
@@ -27,6 +27,8 @@ export interface Linker {
      *
      * @param document A LangiumDocument that shall be linked.
      * @param cancelToken A token for cancelling the operation.
+     *
+     * @throws `OperationCancelled` if a cancellation event is detected
      */
     link(document: LangiumDocument, cancelToken?: CancellationToken): Promise<void>;
 
diff --git a/packages/langium/src/serializer/json-serializer.ts b/packages/langium/src/serializer/json-serializer.ts
@@ -126,9 +126,10 @@ export class DefaultJsonSerializer implements JsonSerializer {
         this.commentProvider = services.documentation.CommentProvider;
     }
 
-    serialize(node: AstNode, options: JsonSerializeOptions = {}): string {
+    serialize(node: AstNode, options?: JsonSerializeOptions): string {
+        const serializeOptions = options ?? {};
         const specificReplacer = options?.replacer;
-        const defaultReplacer = (key: string, value: unknown) => this.replacer(key, value, options);
+        const defaultReplacer = (key: string, value: unknown) => this.replacer(key, value, serializeOptions);
         const replacer = specificReplacer ? (key: string, value: unknown) => specificReplacer(key, value, defaultReplacer) : defaultReplacer;
 
         try {
@@ -139,9 +140,10 @@ export class DefaultJsonSerializer implements JsonSerializer {
         }
     }
 
-    deserialize<T extends AstNode = AstNode>(content: string, options: JsonDeserializeOptions = {}): T {
+    deserialize<T extends AstNode = AstNode>(content: string, options?: JsonDeserializeOptions): T {
+        const deserializeOptions = options ?? {};
         const root = JSON.parse(content);
-        this.linkNode(root, root, options);
+        this.linkNode(root, root, deserializeOptions);
         return root;
     }
 
diff --git a/packages/langium/src/workspace/ast-descriptions.ts b/packages/langium/src/workspace/ast-descriptions.ts
@@ -46,7 +46,8 @@ export class DefaultAstNodeDescriptionProvider implements AstNodeDescriptionProv
         this.nameProvider = services.references.NameProvider;
     }
 
-    createDescription(node: AstNode, name: string | undefined, document: LangiumDocument = getDocument(node)): AstNodeDescription {
+    createDescription(node: AstNode, name: string | undefined, document?: LangiumDocument): AstNodeDescription {
+        const doc = document ?? getDocument(node);
         name ??= this.nameProvider.getName(node);
         const path = this.astNodeLocator.getAstNodePath(node);
         if (!name) {
@@ -62,7 +63,7 @@ export class DefaultAstNodeDescriptionProvider implements AstNodeDescriptionProv
             },
             selectionSegment: toDocumentSegment(node.$cstNode),
             type: node.$type,
-            documentUri: document.uri,
+            documentUri: doc.uri,
             path
         };
     }
diff --git a/packages/langium/src/workspace/workspace-lock.ts b/packages/langium/src/workspace/workspace-lock.ts
@@ -63,12 +63,12 @@ export class DefaultWorkspaceLock implements WorkspaceLock {
         return this.enqueue(this.readQueue, action);
     }
 
-    private enqueue<T = void>(queue: LockEntry[], action: LockAction<T>, cancellationToken?: CancellationToken): Promise<T> {
+    private enqueue<T = void>(queue: LockEntry[], action: LockAction<T>, cancellationToken = CancellationToken.None): Promise<T> {
         const deferred = new Deferred<unknown>();
         const entry: LockEntry = {
             action,
             deferred,
-            cancellationToken: cancellationToken ?? CancellationToken.None
+            cancellationToken
         };
         queue.push(entry);
         this.performNextOperation();
diff --git a/packages/langium/src/workspace/workspace-manager.ts b/packages/langium/src/workspace/workspace-manager.ts
@@ -53,6 +53,9 @@ export interface WorkspaceManager {
      * each language file and stores it locally.
      *
      * @param folders The set of workspace folders to be indexed.
+     * @param cancelToken A cancellation token that can be used to cancel the operation.
+     *
+     * @throws OperationCancelled if a cancellation event has been detected
      */
     initializeWorkspace(folders: WorkspaceFolder[], cancelToken?: CancellationToken): Promise<void>;
 

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,11 @@ export interface DocumentSymbolProvider {`
`21`	`21`	`/**`
`22`	`22`	`* Handle a document symbols request.`
`23`	`23`	`*`
	`24`	`+ * @param document The document in the workspace.`
	`25`	`+ * @param params The parameters of the request.`
	`26`	`+ * @param cancelToken A cancellation token that migh be used to cancel the request.`
	`27`	`+ * @returns The symbols for the given document.`
	`28`	`+ *`
`24`	`29`	* @throws `OperationCancelled` if cancellation is detected during execution
`25`	`30`	* @throws `ResponseError` if an error is detected that should be sent as response to the client
`26`	`31`	`*/`
`@@ -37,7 +42,7 @@ export class DefaultDocumentSymbolProvider implements DocumentSymbolProvider {`
`37`	`42`	`this.nodeKindProvider = services.shared.lsp.NodeKindProvider;`
`38`	`43`	`}`
`39`	`44`
`40`		`- getSymbols(document: LangiumDocument): MaybePromise<DocumentSymbol[]> {`
	`45`	`+ getSymbols(document: LangiumDocument, _params: DocumentSymbolParams, _cancelToken?: CancellationToken): MaybePromise<DocumentSymbol[]> {`
`41`	`46`	`return this.getSymbol(document, document.parseResult.value);`
`42`	`47`	`}`
`43`	`48`