Merge #6622 'api: Deprecate nvim_buf_get_number'

runtime/doc/msgpack_rpc.txt

@@ -197,7 +197,7 @@ prefix is stripped off.
 5. Types							    *rpc-types*
 
 The Nvim C API uses custom types for all functions. |api-types|
-For the purpose of mapping to msgpack, the types can be split into two groups:
+At the RPC layer, the types can be split into two groups:
 
   - Basic types that map natively to msgpack (and probably have a default
     representation in msgpack-supported programming languages)
@@ -219,15 +219,16 @@ Special types (msgpack EXT) ~
   Window                            -> enum value kObjectTypeWindow
   Tabpage                           -> enum value kObjectTypeTabpage
 
-An API method expecting one of these types may be passed an integer instead,
+API functions expecting one of the special EXT types may be passed an integer
-although they are not interchangeable. For example, a Buffer may be passed as
+instead, but not another EXT type. E.g. Buffer may be passed as an integer but
-an integer, but not a Window or Tabpage.
+not as a Window or Tabpage. The EXT object data is the object id encoded as
+a msgpack integer: For buffers this is the |bufnr()| and for windows the
+|window-ID|. For tabpages the id is an internal handle, not the tabpage
+number.
+
+To determine the type codes of the special EXT types, inspect the `types` key
+of the |api-metadata| at runtime. Example JSON representation: >
 
-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
-`nvim_get_api_info` method at runtime. Here's a sample JSON representation of
-the `types` object:
->
   "types": {
     "Buffer": {
       "id": 0,
@@ -242,7 +243,7 @@ the `types` object:
       "prefix": "nvim_tabpage_"
     }
   }
-<
+
 Even for statically compiled clients it is good practice to avoid hardcoding
 the type codes, because a client may be built against one Nvim version but
 connect to another with different type codes.

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)