Provide hover documentation on keywords (#1842)

Author: ydaveluy

packages/langium/src/lsp/hover-provider.ts

@@ -13,7 +13,10 @@ import type { AstNode } from '../syntax-tree.js';
 import type { MaybePromise } from '../utils/promise-utils.js';
 import type { LangiumDocument } from '../workspace/documents.js';
 import type { DocumentationProvider } from '../documentation/documentation-provider.js';
-import { findDeclarationNodeAtOffset } from '../utils/cst-utils.js';
+import { findCommentNode, findDeclarationNodeAtOffset } from '../utils/cst-utils.js';
+import { isKeyword } from '../languages/generated/ast.js';
+import { isJSDoc, parseJSDoc } from '../documentation/jsdoc.js';
+import { isAstNodeWithComment } from '../serializer/json-serializer.js';
 
 /**
  * Language-specific service for handling hover requests.
@@ -48,13 +51,36 @@ export abstract class AstNodeHoverProvider implements HoverProvider {
                 if (targetNode) {
                     return this.getAstNodeHoverContent(targetNode);
                 }
+
+                // Add support for documentation on keywords
+                if (isKeyword(cstNode.grammarSource)) {
+                    return this.getKeywordHoverContent(cstNode.grammarSource);
+                }
             }
         }
         return undefined;
     }
 
     protected abstract getAstNodeHoverContent(node: AstNode): MaybePromise<Hover | undefined>;
 
+    protected getKeywordHoverContent(node: AstNode): MaybePromise<Hover | undefined> {
+        let comment = isAstNodeWithComment(node) ? node.$comment : undefined;
+        if (!comment) {
+            comment = findCommentNode(node.$cstNode, ['ML_COMMENT'])?.text;
+        }
+        if (comment && isJSDoc(comment)) {
+            const content = parseJSDoc(comment).toMarkdown();
+            if (content) {
+                return {
+                    contents: {
+                        kind: 'markdown',
+                        value: content
+                    }
+                };
+            }
+        }
+        return undefined;
+    }
 }
 
 export class MultilineCommentHoverProvider extends AstNodeHoverProvider {

packages/langium/test/lsp/hover.test.ts

@@ -4,12 +4,15 @@
  * terms of the MIT License, which is available in the project root.
  ******************************************************************************/
 
-import { describe, test } from 'vitest';
+import { beforeAll, describe, test } from 'vitest';
+import type { AsyncDisposable} from 'langium';
 import { EmptyFileSystem } from 'langium';
-import { createLangiumGrammarServices } from 'langium/grammar';
+import { createLangiumGrammarServices, createServicesForGrammar } from 'langium/grammar';
+import type { ExpectedHover} from 'langium/test';
 import { expectHover } from 'langium/test';
 
-const text = `
+describe('Hover', () => {
+    const text = `
   /**
    * I am a grammar file comment
    */
@@ -27,12 +30,10 @@ const text = `
    * Hi I reference Rule {@linkcode X}
    */
   <|>Y: value=<|>X;
-  `;
-
-const grammarServices = createLangiumGrammarServices(EmptyFileSystem).grammar;
-const hover = expectHover(grammarServices);
+    `;
 
-describe('Hover', () => {
+    const grammarServices = createLangiumGrammarServices(EmptyFileSystem).grammar;
+    const hover = expectHover(grammarServices);
 
     test('Hovering over whitespace should not provide a hover', async () => {
         await hover({
@@ -74,3 +75,58 @@ describe('Hover', () => {
         });
     });
 });
+
+describe('Hover on keywords', () => {
+
+    const grammar = `grammar HoverOnKeywords
+
+    entry Model:
+        /** root keyword */ 'root' name=ID
+        elements+=Tag*;
+
+    Tag: /** opening tag */ 'tag' name=ID /** closing tag */ 'tag';
+
+    hidden terminal WS: /\\s+/;
+    terminal ID: /[_a-zA-Z][\\w_]*/;
+    hidden terminal ML_COMMENT: /#\\*[\\s\\S]*?\\*#/;
+    hidden terminal SL_COMMENT: /##[^\\n\\r]*/;
+    `;
+
+    const text = `
+    ## SL_COMMENT
+    <|>root name
+    #* ML_COMMENT *#
+    <|>tag first <|>tag
+      `;
+
+    let hover: (expectedHover: ExpectedHover) => Promise<AsyncDisposable>;
+
+    beforeAll(async () => {
+        const services = await createServicesForGrammar({
+            grammar
+        });
+        hover = expectHover(services);
+    });
+    test('Hovering over root keyword', async () => {
+        await hover({
+            text,
+            index: 0,
+            hover: 'root keyword'
+        });
+    });
+    test('Hovering over opening tag keyword', async () => {
+
+        await hover({
+            text,
+            index: 1,
+            hover: 'opening tag'
+        });
+    });
+    test('Hovering over closing tag keyword', async () => {
+        await hover({
+            text,
+            index: 2,
+            hover: 'closing tag'
+        });
+    });
+});