From a29297ac538f9a86bbcd5e59cc8a9e3494b263c6 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Tue, 4 Aug 2026 04:19:54 -0500
Subject: [PATCH] docs(api): buffer columns are byte indices #41137

---
 runtime/doc/api.txt            | 3 ++-
 runtime/doc/diagnostic.txt     | 7 ++++---
 runtime/lua/vim/diagnostic.lua | 6 +++---
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ecc4683389..133328071e 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -146,7 +146,8 @@ Special types (msgpack EXT) ~
 
                                                         *api-indexing*
 Most of the API uses 0-based indices, and ranges are end-exclusive. For the
-end of a range, -1 denotes the last line/column. See |vim.pos|, |vim.range|
+end of a range, -1 denotes the last line/column. A column in buffer text is a
+byte index, not a character index or screen cell. See |vim.pos|, |vim.range|
 for representing and converting positions.
 
 Exception: the following API functions use "mark-like" indexing (1-based
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index f02462a740..222b44e866 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -442,8 +442,9 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
 
                                                         *diagnostic-structure*
 
-    Diagnostics use |api-indexing| (i.e. 0-based rows and columns). See also
-    |vim.pos| and |vim.range| to convert positions from other systems.
+    Diagnostics use |api-indexing| (i.e. 0-based rows, and columns given as
+    0-based byte indices). See also |vim.pos| and |vim.range| to convert
+    positions from other systems.
 
     Fields: ~
       • {bufnr}       (`integer`) Buffer number
@@ -458,7 +459,7 @@ Lua module: vim.diagnostic                                    *diagnostic-api*
 
 *vim.Diagnostic.Set*
     Diagnostics use the same indexing as the rest of the Nvim API (i.e.
-    0-based rows and columns). |api-indexing|
+    0-based rows, and columns given as 0-based byte indices). |api-indexing|
 
     Fields: ~
       • {code}?       (`string|integer`) The diagnostic code
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index fc800cf8b2..cbd7e8f5d1 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -14,7 +14,7 @@ local M = vim._defer_require('vim.diagnostic', {
 })
 
 --- Diagnostics use the same indexing as the rest of the Nvim API (i.e. 0-based
---- rows and columns). |api-indexing|
+--- rows, and columns given as 0-based byte indices). |api-indexing|
 --- @class vim.Diagnostic.Set
 ---
 --- The starting line of the diagnostic (0-indexed)
@@ -52,8 +52,8 @@ local M = vim._defer_require('vim.diagnostic', {
 
 --- [diagnostic-structure]()
 ---
---- Diagnostics use |api-indexing| (i.e. 0-based rows and columns). See also |vim.pos| and
---- |vim.range| to convert positions from other systems.
+--- Diagnostics use |api-indexing| (i.e. 0-based rows, and columns given as 0-based byte
+--- indices). See also |vim.pos| and |vim.range| to convert positions from other systems.
 ---
 --- @class vim.Diagnostic : vim.Diagnostic.Set
 --- @field bufnr integer Buffer number