api: deprecate obsolete nvim_buf_get_number function

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

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

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

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)