From bf73e63a2dee364df4b9578df635a71cefd07068 Mon Sep 17 00:00:00 2001
From: ushen-pyj <83943557+ushen-pyj@users.noreply.github.com>
Date: Thu, 30 Oct 2025 16:56:29 +0800
Subject: [PATCH 1/3] Enhance source handling in find-source.lua and introduce
 virtual node marking in luadoc.lua. Skip virtual sources during function
 checks and ensure documentation nodes are marked as virtual for better
 processing.

---
 script/core/find-source.lua | 3 +++
 script/parser/luadoc.lua    | 9 +++++++++
 2 files changed, 12 insertions(+)

diff --git a/script/core/find-source.lua b/script/core/find-source.lua
index c5d52f3e4..8b5755d8b 100644
--- a/script/core/find-source.lua
+++ b/script/core/find-source.lua
@@ -15,6 +15,9 @@ return function (state, position, accept)
     local len = math.huge
     local result
     guide.eachSourceContain(state.ast, position, function (source)
+        if source.virtual then
+            return
+        end
         if source.type == 'function' then
             if not isValidFunctionPos(source, position) then
                 return
diff --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua
index 72e5dc18d..056a21058 100644
--- a/script/parser/luadoc.lua
+++ b/script/parser/luadoc.lua
@@ -2308,6 +2308,14 @@ local function luadoc(state)
     bindDocs(state)
 end
 
+local function markVirtual(node)
+    if not node then
+        return
+    end
+    node.virtual = true
+    guide.eachChild(node, markVirtual)
+end
+
 return {
     buildAndBindDoc = function (ast, src, comment, group)
         local doc = buildLuaDoc(comment)
@@ -2317,6 +2325,7 @@ return {
             doc.special = src
             doc.originalComment = comment
             doc.virtual = true
+            markVirtual(doc)
             doc.specialBindGroup = group
             ast.state.pluginDocs = pluginDocs
             return doc

From 67c9d9e19da9538afc163a7e480e3a4ef6640cd4 Mon Sep 17 00:00:00 2001
From: ushen-pyj <83943557+ushen-pyj@users.noreply.github.com>
Date: Thu, 30 Oct 2025 17:02:25 +0800
Subject: [PATCH 2/3] Remove virtual node marking from documentation in
 luadoc.lua to streamline processing of plugin documentation.

---
 script/parser/luadoc.lua | 1 -
 1 file changed, 1 deletion(-)

diff --git a/script/parser/luadoc.lua b/script/parser/luadoc.lua
index 056a21058..ad22af1d7 100644
--- a/script/parser/luadoc.lua
+++ b/script/parser/luadoc.lua
@@ -2324,7 +2324,6 @@ return {
             pluginDocs[#pluginDocs+1] = doc
             doc.special = src
             doc.originalComment = comment
-            doc.virtual = true
             markVirtual(doc)
             doc.specialBindGroup = group
             ast.state.pluginDocs = pluginDocs

From f6053a9b4f9a697eec80adeb31b5c1ed0cbd43e9 Mon Sep 17 00:00:00 2001
From: ushen-pyj <83943557+ushen-pyj@users.noreply.github.com>
Date: Thu, 30 Oct 2025 17:07:10 +0800
Subject: [PATCH 3/3] Update changelog.md to include fix for plugin virtual
 comment style and behavior issues

---
 changelog.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/changelog.md b/changelog.md
index 33fc397b6..a8972dfdd 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 -->
+* `FIX` Plugin virtual comment style and behavior issues
 * `FIX` Incorrect generation of function signatures with tuple-parameters
 * `NEW` Doc output now contains file paths for `@alias` and `@enum` types
 * `FIX` Typos in a few error messages.