add: resolve links to symbols in markdown descriptions

script/core/completion/completion.lua

@@ -2256,6 +2256,37 @@ local function tryluaDocOfFunction(doc, results, pad)
     }
 end
 
+---Checks for a lua symbol reference in comment and returns an async callback if found
+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), "%)?(.*)//:aul%(%]", #line - col)
+
+    if symbol then
+        -- flip it back the right way around
+        symbol = string.reverse(symbol)
+
+        ---@async
+        return function ()
+            for _, match in ipairs(wssymbol(symbol)) do
+                results[#results+1] = {
+                    label = match.name,
+                    kind = define.CompletionItemKind.Class,
+                    insertText = match.name
+                }
+            end
+        end
+    end
+end
+
 ---@async
 local function tryLuaDoc(state, position, results)
     local doc = getLuaDoc(state, position)
@@ -2327,8 +2358,13 @@ end
 ---@async
 local function tryCompletions(state, position, triggerCharacter, results)
     if getComment(state, position) then
+        local callback = trySymbolReference(state, position, results)
+        if callback then
+            callback()
+        else
+            tryComment(state, position, results)
+        end
         tryLuaDoc(state, position, results)
-        tryComment(state, position, results)
         return
     end
     if postfix(state, position, results) then

script/provider/markdown.lua

@@ -1,10 +1,41 @@
+local wssymbol = require("core.workspace-symbol")
+local guide = require("parser.guide")
+
 ---@class markdown
 local mt = {}
 mt.__index = mt
 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