From 5acb2a1d3398f292c98a7bbfc1e58d54037fbb9b Mon Sep 17 00:00:00 2001
From: Puneet Dixit <puneetdixit4321@gmail.com>
Date: Wed, 27 May 2026 19:51:45 +0530
Subject: [PATCH] docs(lsp): document on_list deduplication #39941

Problem:
Deduplicating LSP locations in the default handler changes list behavior for every user, while some configurations may intentionally return matching locations from multiple clients.

Solution:
Document how users can deduplicate locations in an on_list handler with vim.list.unique().

Co-authored-by: Deepak kudi <deepakkudi23@adsl-172-10-9-116.dsl.sndg02.sbcglobal.net>
Co-authored-by: Puneet Dixit <236133619+puneetdixit200@users.noreply.github.com>
---
 runtime/doc/lsp.txt         | 21 +++++++++++++++++++++
 runtime/lua/vim/lsp/buf.lua | 20 ++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index c0a2afb94d..9f82f01690 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1442,6 +1442,27 @@ the current buffer.
                         vim.lsp.buf.references(nil, { on_list = on_list })
 <
 
+                    The list can be transformed before it is shown. For
+                    example, to remove duplicate locations returned by
+                    multiple clients: >lua
+                        local function on_list(what)
+                          vim.list.unique(what.items, function(item)
+                            return ('%s\0%d\0%d\0%d\0%d'):format(
+                              item.filename or '',
+                              item.lnum or 0,
+                              item.col or 0,
+                              item.end_lnum or 0,
+                              item.end_col or 0
+                            )
+                          end)
+                          vim.fn.setqflist({}, ' ', what)
+                          vim.cmd('botright copen')
+                        end
+
+                        vim.lsp.buf.definition({ on_list = on_list })
+                        vim.lsp.buf.references(nil, { on_list = on_list })
+<
+
                     See |setqflist-what| for the structure of the `what`
                     parameter.
       • {pos}       (`vim.Pos`, default: cursor position) Position on a buffer
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index 306ffa5c0d..2eef37458e 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/runtime/lua/vim/lsp/buf.lua
@@ -332,6 +332,26 @@ end
 --- vim.lsp.buf.definition({ on_list = on_list })
 --- vim.lsp.buf.references(nil, { on_list = on_list })
 --- ```
+--- The list can be transformed before it is shown. For example, to remove
+--- duplicate locations returned by multiple clients:
+--- ```lua
+--- local function on_list(what)
+---   vim.list.unique(what.items, function(item)
+---     return ('%s\0%d\0%d\0%d\0%d'):format(
+---       item.filename or '',
+---       item.lnum or 0,
+---       item.col or 0,
+---       item.end_lnum or 0,
+---       item.end_col or 0
+---     )
+---   end)
+---   vim.fn.setqflist({}, ' ', what)
+---   vim.cmd('botright copen')
+--- end
+---
+--- vim.lsp.buf.definition({ on_list = on_list })
+--- vim.lsp.buf.references(nil, { on_list = on_list })
+--- ```
 --- See |setqflist-what| for the structure of the `what` parameter.
 --- @field on_list? fun(what: vim.fn.setqflist.what)
 ---