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)
 ---