Merge pull request #2656 from carsakiller/2175-md-symbol-reference

add: resolve links to symbols in markdown descriptions

3 files changed, 64 insertions, 2 deletions

diff --git a/changelog.md b/changelog.md
index 62ca8974..315fa729 100644
--- a/changelog.md
+++ b/changelog.md
@@ -2,6 +2,7 @@
 
 ## Unreleased
 <!-- Add all new changes here. They will be moved under a version at release -->
+* `NEW` Reference workspace symbols in comments using `[some text](lua://symbolName)` syntax
 
 ## 3.9.0
 `2024-5-11`
diff --git a/script/core/completion/completion.lua b/script/core/completion/completion.lua
index d047dd56..5c55c16b 100644
--- a/script/core/completion/completion.lua
+++ b/script/core/completion/completion.lua
@@ -1546,7 +1546,7 @@ local function tryWord(state, position, triggerCharacter, results)
                     local env = guide.getENV(state.ast, startPos)
                     if env then
                         checkGlobal(state, word, startPos, position, env, false, results)
-                        checkModule(state, word, startPos, results) 
+                        checkModule(state, word, startPos, results)
                     end
                 end
             end
@@ -2256,6 +2256,35 @@ local function tryluaDocOfFunction(doc, results, pad)
     }
 end
 
+---Checks for a lua symbol reference in comment
+---@async
+local function trySymbolReference(state, position, results)
+    local doc = getLuaDoc(state, position)
+    if not doc then
+        return
+    end
+
+    local line = doc.originalComment.text ---@type string
+    local col = select(2, guide.rowColOf(position)) - 2 ---@type integer
+
+    -- User will ask for completion at end of symbol name so we need to perform a reverse match to see if they are in a symbol reference
+    -- Matching in reverse allows the symbol to be of any length and we can still match all the way back to `](lua://` from right to left
+    local symbol = string.match(string.reverse(line), "%)?([%w%s-_.*]*)//:aul%(%]", #line - col)
+
+    if symbol then
+        -- flip it back the right way around
+        symbol = string.reverse(symbol)
+
+        for _, match in ipairs(wssymbol(symbol)) do
+            results[#results+1] = {
+                label = match.name,
+                kind = define.CompletionItemKind.Class,
+                insertText = match.name
+            }
+        end
+    end
+end
+
 ---@async
 local function tryLuaDoc(state, position, results)
     local doc = getLuaDoc(state, position)
@@ -2327,6 +2356,7 @@ end
 ---@async
 local function tryCompletions(state, position, triggerCharacter, results)
     if getComment(state, position) then
+        trySymbolReference(state, position, results)
         tryLuaDoc(state, position, results)
         tryComment(state, position, results)
         return
diff --git a/script/provider/markdown.lua b/script/provider/markdown.lua
index fe1b26b2..b5478567 100644
--- a/script/provider/markdown.lua
+++ b/script/provider/markdown.lua
@@ -1,3 +1,6 @@
+local wssymbol = require("core.workspace-symbol")
+local guide = require("parser.guide")
+
 ---@class markdown
 local mt = {}
 mt.__index = mt
@@ -5,6 +8,34 @@ mt.__name = 'markdown'
 
 mt._splitLine = false
 
+---@async
+---Converts `[mySymbol](lua://mySymbol)` into a link that points to the origin of `mySymbol`.
+---@param txt string
+local function processSymbolReferences(txt)
+	local function replacer(linkText, symbol)
+		local source ---@type table
+
+		for _, match in ipairs(wssymbol(symbol)) do
+			if match.name == symbol then
+				source = match.source
+				break
+			end
+		end
+
+		if not source then
+			log.warn(string.format("Failed to find source of %q symbol in markdown comment", symbol))
+			return
+		end
+
+		local row, _ = guide.rowColOf(source.start)
+		local uri = string.format("%s#%i", guide.getUri(source), row + 1)
+
+		return string.format("[%s](%s)", linkText, uri)
+	end
+
+	return string.gsub(txt, "%[([^]]*)%]%(lua://([^)]+)%)", replacer)
+end
+
 function mt:__tostring()
     return self:string()
 end
@@ -104,7 +135,7 @@ function mt:string(nl)
                         end
                     end
                 end
-                lines[#lines+1] = obj.text
+                lines[#lines + 1] = processSymbolReferences(obj.text)
                 language = obj.language
             end
         end