From c6e3d4c29c86282b6612f6ae2b9a3222d9c68963 Mon Sep 17 00:00:00 2001
From: Henner Zeller <hzeller@google.com>
Date: Fri, 11 Feb 2022 15:11:57 -0800
Subject: [PATCH] Sketch out next steps in language server features

  * File feature requests #1187, #1188, #1189, #1190
  * Reference these in the README to easily follow progress
  * Write JSON RPC protocol definition for these features.

Signed-off-by: Henner Zeller <hzeller@google.com>
---
 common/lsp/lsp-protocol.yaml | 51 ++++++++++++++++++++++++++++++++++++
 verilog/tools/ls/README.md   |  5 ++++
 2 files changed, 56 insertions(+)

diff --git a/common/lsp/lsp-protocol.yaml b/common/lsp/lsp-protocol.yaml
index 8af97fa26..5fbbb6e98 100644
--- a/common/lsp/lsp-protocol.yaml
+++ b/common/lsp/lsp-protocol.yaml
@@ -41,6 +41,10 @@ Range:
 TextDocumentIdentifier:
   uri: string
 
+Location:
+  <: TextDocumentIdentifier
+  range: Range
+
 TextDocumentItem:
   <:TextDocumentIdentifier
   text: string
@@ -126,3 +130,50 @@ DocumentHighlight:         # response documentHighlight is [] of this.
 DocumentFormattingParams:
   textDocument: TextDocumentIdentifier
   range?: Range               # only used for textDocument/rangeFormatting
+
+# -- textDocument/hover
+# https://github.com/chipsalliance/verible/issues/1187
+HoverParams:
+  <: TextDocumentPositionParams
+
+MarkupContent:
+  kind: string = "markdown"
+  value: string
+
+Hover:
+  contents: MarkupContent
+  range?: Range
+
+# == The following are not yet implemented. Steps needed ==
+#  o need to be able to set up a project (knowing which files are relevant,
+#    which might require some sort of run through the build system.
+#    And convey that to the language server
+#    https://github.com/chipsalliance/verible/issues/1188
+#  o Use the symbol table with the above project (and fix all known bugs there)
+
+# -- textDocument/definition    (requires project + active symbol table #1189)
+DefinitionParams:
+  <: TextDocumentPositionParams
+
+# Response Location[]
+
+# -- textDocument/declaration   (requires project + active symbol table #1189)
+DeclarationParams:
+  <: TextDocumentPositionParams
+
+# Response: Location[]
+
+# -- textDocument/references   (requires project + active symbol table #1189)
+ReferenceParams:
+  <: TextDocumentPositionParams
+
+# Response: Location[]
+
+# -- textDocument/documentLink  (e.g. include files; requires project #1190)
+DocumentLinkParams:
+  textDocument: TextDocumentIdentifier
+
+# Response is a DocumentLink[]
+DocumentLink:
+  range: Range
+  target?: string  # DocumentUri
diff --git a/verilog/tools/ls/README.md b/verilog/tools/ls/README.md
index f04d75b01..bf7f63fc4 100644
--- a/verilog/tools/ls/README.md
+++ b/verilog/tools/ls/README.md
@@ -19,7 +19,12 @@ progress
   - [x] Provide formatting.
   - [x] Highlight all the symbols that are the same as current under cursor.
     - [ ] Take scope and type into account to only highlight _same_ symbols.
+  - [ ] Provide useful information on hover
+        ([#1187](https://github.com/chipsalliance/verible/issues/1187))
   - [ ] Find definition of symbol even if in another file.
+        ([#1189](https://github.com/chipsalliance/verible/issues/1189))
+  - [ ] Provide Document Links (e.g. opening include files)
+        ([#1190](https://github.com/chipsalliance/verible/issues/1190))
   - [ ] Rename refactor a symbol
 
 ## Hooking up to editor