Merge pull request #235 from bash-lsp/comments-as-documentation

Use comments as symbol documentation

Author: skovhus

server/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Bash Language Server
 
+## 1.15.0
+
+* Use comments above symbols for documentation (https://github.com/bash-lsp/bash-language-server/pull/234, https://github.com/bash-lsp/bash-language-server/pull/235)
+
+
 ## 1.14.0
 
 * onHover and onCompletion documentation improvements (https://github.com/bash-lsp/bash-language-server/pull/230)

server/package.json

@@ -3,7 +3,7 @@
   "description": "A language server for Bash",
   "author": "Mads Hartmann",
   "license": "MIT",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "publisher": "mads-hartmann",
   "main": "./out/server.js",
   "typings": "./out/server.d.ts",

server/src/__tests__/server.test.ts

@@ -367,18 +367,20 @@ describe('server', () => {
     )
 
     expect(resultFunction).toMatchInlineSnapshot(`
-      Array [
-        Object {
-          "data": Object {
-            "name": "add_a_user",
-            "type": 3,
-          },
-          "documentation": "Function defined in ../issue101.sh",
-          "kind": 3,
-          "label": "add_a_user",
-        },
-      ]
-    `)
+Array [
+  Object {
+    "data": Object {
+      "name": "add_a_user",
+      "type": 3,
+    },
+    "documentation": "Function defined in ../issue101.sh
+
+Helper function to add a user",
+    "kind": 3,
+    "label": "add_a_user",
+  },
+]
+`)
   })
 
   it('responds to onCompletion with local symbol when word is found in multiple files', async () => {

server/src/server.ts

@@ -135,6 +135,54 @@ export default class BashServer {
     )
   }
 
+  private getDocumentationForSymbol({
+    currentUri,
+    symbol,
+  }: {
+    symbol: LSP.SymbolInformation
+    currentUri: string
+  }): string {
+    const symbolUri = symbol.location.uri
+    const symbolStarLine = symbol.location.range.start.line
+
+    const commentAboveSymbol = this.analyzer.commentsAbove(symbolUri, symbolStarLine)
+    const symbolDocumentation = commentAboveSymbol ? `\n\n${commentAboveSymbol}` : ''
+
+    return symbolUri !== currentUri
+      ? `${symbolKindToDescription(symbol.kind)} defined in ${path.relative(
+          currentUri,
+          symbolUri,
+        )}${symbolDocumentation}`
+      : `${symbolKindToDescription(symbol.kind)} defined on line ${symbolStarLine +
+          1}${symbolDocumentation}`
+  }
+
+  private getCompletionItemsForSymbols({
+    symbols,
+    currentUri,
+  }: {
+    symbols: LSP.SymbolInformation[]
+    currentUri: string
+  }): BashCompletionItem[] {
+    return deduplicateSymbols({ symbols, currentUri }).map(
+      (symbol: LSP.SymbolInformation) => ({
+        label: symbol.name,
+        kind: symbolKindToCompletionKind(symbol.kind),
+        data: {
+          name: symbol.name,
+          type: CompletionItemDataType.Symbol,
+        },
+        documentation:
+          symbol.location.uri !== currentUri
+            ? this.getDocumentationForSymbol({
+                currentUri,
+                symbol,
+              })
+            : undefined,
+      }),
+    )
+  }
+
   private async onHover(
     params: LSP.TextDocumentPositionParams,
   ): Promise<LSP.Hover | null> {
@@ -180,11 +228,6 @@ export default class BashServer {
         return { contents: getMarkdownContent(shellDocumentation) }
       }
     } else {
-      const getCommentsAbove = (uri: string, line: number): string => {
-        const comment = this.analyzer.commentsAbove(uri, line)
-        return comment ? `\n\n${comment}` : ''
-      }
-
       const symbolDocumentation = deduplicateSymbols({
         symbols: this.analyzer.findSymbolsMatchingWord({
           exactMatch: true,
@@ -195,19 +238,7 @@ export default class BashServer {
         // do not return hover referencing for the current line
         .filter(symbol => symbol.location.range.start.line !== params.position.line)
         .map((symbol: LSP.SymbolInformation) =>
-          symbol.location.uri !== currentUri
-            ? `${symbolKindToDescription(symbol.kind)} defined in ${path.relative(
-                currentUri,
-                symbol.location.uri,
-              )}${getCommentsAbove(
-                symbol.location.uri,
-                symbol.location.range.start.line,
-              )}`
-            : `${symbolKindToDescription(symbol.kind)} defined on line ${symbol.location
-                .range.start.line + 1}${getCommentsAbove(
-                params.textDocument.uri,
-                symbol.location.range.start.line,
-              )}`,
+          this.getDocumentationForSymbol({ currentUri, symbol }),
         )
 
       if (symbolDocumentation.length === 1) {
@@ -268,7 +299,7 @@ export default class BashServer {
     const symbolCompletions =
       word === null
         ? []
-        : getCompletionItemsForSymbols({
+        : this.getCompletionItemsForSymbols({
             symbols: this.analyzer.findSymbolsMatchingWord({
               exactMatch: false,
               word,
@@ -391,32 +422,6 @@ function deduplicateSymbols({
   return uniqueBasedOnHash([...symbolsCurrentFile, ...symbolsOtherFiles], getSymbolId)
 }
 
-function getCompletionItemsForSymbols({
-  symbols,
-  currentUri,
-}: {
-  symbols: LSP.SymbolInformation[]
-  currentUri: string
-}): BashCompletionItem[] {
-  return deduplicateSymbols({ symbols, currentUri }).map(
-    (symbol: LSP.SymbolInformation) => ({
-      label: symbol.name,
-      kind: symbolKindToCompletionKind(symbol.kind),
-      data: {
-        name: symbol.name,
-        type: CompletionItemDataType.Symbol,
-      },
-      documentation:
-        symbol.location.uri !== currentUri
-          ? `${symbolKindToDescription(symbol.kind)} defined in ${path.relative(
-              currentUri,
-              symbol.location.uri,
-            )}`
-          : undefined,
-    }),
-  )
-}
-
 function symbolKindToCompletionKind(s: LSP.SymbolKind): LSP.CompletionItemKind {
   switch (s) {
     case LSP.SymbolKind.File:

testing/fixtures/issue101.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
-# A simple script with a function...
 
+# Helper function to add a user
 add_a_user()
 {
   USER=$1