Merge pull request bash-lsp#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