api: deprecate obsolete nvim_buf_get_number function

4 files changed, 15 insertions, 1 deletions

diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 261e68cfb1..c5c0392d96 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -221,7 +221,10 @@ Special types (msgpack EXT) ~
 
 An API method expecting one of these types may be passed an integer instead,
 although they are not interchangeable. For example, a Buffer may be passed as
-an integer, but not a Window or Tabpage.
+an integer, but not as a Window or Tabpage. The data in the EXT object is the
+object id encodes as a msgpack integer. For buffers this is equal to the
+buffer number and for windows the window id. For tabpages this is not equal to
+tabpage numbers.
 
 The most reliable way of determining the type codes for the special Nvim types
 is to inspect the `types` key of metadata dictionary returned by the
diff --git a/scripts/gendispatch.lua b/scripts/gendispatch.lua
index 0ee3ae6475..c0291c55d3 100644
--- a/scripts/gendispatch.lua
+++ b/scripts/gendispatch.lua
@@ -37,6 +37,8 @@ c_proto = Ct(
   fill * P('(') * fill * Cg(c_params, 'parameters') * fill * P(')') *
   Cg(Cc(false), 'async') *
   (fill * Cg((P('FUNC_API_SINCE(') * C(num ^ 1)) * P(')'), 'since') ^ -1) *
+  (fill * Cg((P('FUNC_API_DEPRECATED_SINCE(') * C(num ^ 1)) * P(')'),
+              'deprecated_since') ^ -1) *
   (fill * Cg((P('FUNC_API_ASYNC') * Cc(true)), 'async') ^ -1) *
   (fill * Cg((P('FUNC_API_NOEXPORT') * Cc(true)), 'noexport') ^ -1) *
   (fill * Cg((P('FUNC_API_NOEVAL') * Cc(true)), 'noeval') ^ -1) *
@@ -122,6 +124,10 @@ for i,f in ipairs(shallowcopy(functions)) do
       os.exit(1)
     end
     f.since = tonumber(f.since)
+    if f.deprecated_since ~= nil then
+      f.deprecated_since = tonumber(f.deprecated_since)
+    end
+
     if startswith(f.name, "nvim_buf_") then
       ismethod = true
     elseif startswith(f.name, "nvim_win_") then
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index ae5728ee21..5de1535bce 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -567,11 +567,15 @@ void nvim_buf_set_option(Buffer buffer, String name, Object value, Error *err)
 
 /// Gets the buffer number
 ///
+/// @deprecated The buffer number now is equal to the object id,
+///             so there is no need to use this function.
+///
 /// @param buffer     Buffer handle
 /// @param[out] err   Error details, if any
 /// @return Buffer number
 Integer nvim_buf_get_number(Buffer buffer, Error *err)
     FUNC_API_SINCE(1)
+    FUNC_API_DEPRECATED_SINCE(2)
 {
   Integer rv = 0;
   buf_T *buf = find_buffer_by_handle(buffer, err);
diff --git a/src/nvim/func_attr.h b/src/nvim/func_attr.h
index 18410445e1..756c6d05ee 100644
--- a/src/nvim/func_attr.h
+++ b/src/nvim/func_attr.h
@@ -187,6 +187,7 @@
 # define FUNC_API_NOEXPORT
 # define FUNC_API_NOEVAL
 # define FUNC_API_SINCE(X)
+# define FUNC_API_DEPRECATED_SINCE(X)
 # define FUNC_ATTR_MALLOC REAL_FATTR_MALLOC
 # define FUNC_ATTR_ALLOC_SIZE(x) REAL_FATTR_ALLOC_SIZE(x)
 # define FUNC_ATTR_ALLOC_SIZE_PROD(x, y) REAL_FATTR_ALLOC_SIZE_PROD(x, y)