Merge #5752 from justinmk/doc

doc: api_info(), typval_encode.h

5 files changed, 30 insertions, 13 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 976b852bdb..171b0124f6 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -49,15 +49,20 @@ Tabpage				  -> enum value kObjectTypeTabpage
 ==============================================================================
 3. API metadata							 *api-metadata*
 
-Nvim exposes metadata about the API as a Dictionary with the following keys:
-
-version		Nvim version, API level/compatibility
-functions  	API function signatures
-types		Custom handle types defined by Nvim
-error_types	Possible error types returned by API functions
-
-This metadata is mostly useful for external programs accessing the API via
-RPC, see |rpc-api|.
+Nvim exposes API metadata as a Dictionary. Some items are described below:
+
+version			Nvim version, API level/compatibility
+version.api_level	Current API level
+version.api_compatible	API is backwards-compatible with this level
+version.api_prerelease	Declares the current API level as unstable >
+			(version.api_prerelease && fn.since == version.api_level)
+functions		API function signatures
+{fn}.since		API level where function {fn} was introduced
+{fn}.deprecated_since	API level where function {fn} was deprecated
+types			Custom handle types defined by Nvim
+error_types		Possible error types returned by API functions
+
+External programs ("clients") can use the metadata to discover the |rpc-api|.
 
 ==============================================================================
 4. Buffer highlighting					       *api-highlights*
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index bd83b1ff1d..72db7c0782 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -472,6 +472,8 @@ static inline void typval_encode_dict_end(EncodedData *const edata)
 #define TYPVAL_ENCODE_CONV_RECURSE(val, conv_type) \
     TYPVAL_ENCODE_CONV_NIL()
 
+// object_convert_one_value()
+// encode_vim_to_object()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(static, object, EncodedData *const, edata)
 
 #undef TYPVAL_ENCODE_CONV_STRING
diff --git a/src/nvim/eval.c b/src/nvim/eval.c
index a02ca40173..71d60d6b45 100644
--- a/src/nvim/eval.c
+++ b/src/nvim/eval.c
@@ -18242,6 +18242,8 @@ void free_tv(typval_T *varp)
 
 #define TYPVAL_ENCODE_CONV_RECURSE(ignored1, ignored2)
 
+// nothing_convert_one_value()
+// encode_vim_to_nothing()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(static, nothing, void *, ignored)
 
 #undef TYPVAL_ENCODE_ALLOW_SPECIALS
diff --git a/src/nvim/eval/encode.c b/src/nvim/eval/encode.c
index f6c58d8562..869eae74a3 100644
--- a/src/nvim/eval/encode.c
+++ b/src/nvim/eval/encode.c
@@ -383,6 +383,8 @@ int encode_read_from_list(ListReaderState *const state, char *const buf,
 
 #define TYPVAL_ENCODE_ALLOW_SPECIALS false
 
+// string_convert_one_value()
+// encode_vim_to_string()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(static, string, garray_T *const, gap)
 
 #undef TYPVAL_ENCODE_CONV_RECURSE
@@ -413,6 +415,8 @@ TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(static, string, garray_T *const, gap)
       return OK; \
     } while (0)
 
+// echo_convert_one_value()
+// encode_vim_to_echo()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(, echo, garray_T *const, gap)
 
 #undef TYPVAL_ENCODE_CONV_RECURSE
@@ -704,6 +708,8 @@ bool encode_check_json_key(const typval_T *const tv)
       } \
     } while (0)
 
+// json_convert_one_value()
+// encode_vim_to_json()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(static, json, garray_T *const, gap)
 
 #undef TYPVAL_ENCODE_CONV_STRING
@@ -886,6 +892,8 @@ char *encode_tv2json(typval_T *tv, size_t *len)
 
 #define TYPVAL_ENCODE_ALLOW_SPECIALS true
 
+// msgpack_convert_one_value()
+// encode_vim_to_msgpack()
 TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(, msgpack, msgpack_packer *const, packer)
 
 #undef TYPVAL_ENCODE_CONV_STRING
diff --git a/src/nvim/eval/typval_encode.h b/src/nvim/eval/typval_encode.h
index 98fa7b26c6..868877bd47 100644
--- a/src/nvim/eval/typval_encode.h
+++ b/src/nvim/eval/typval_encode.h
@@ -212,10 +212,9 @@ static inline size_t tv_strlen(const typval_T *const tv)
           : strlen((char *) tv->vval.v_string));
 }
 
-/// Define functions which convert VimL value to something else
-///
-/// Creates function `vim_to_{name}(firstargtype firstargname, typval_T *const
-/// tv)` which returns OK or FAIL and helper functions.
+/// Define functions to convert a VimL value:
+///   `{name}_convert_one_value(...)`
+///   `encode_vim_to_{name}(...)`
 ///
 /// @param  scope  Scope of the main function: either nothing or `static`.
 /// @param  name  Name of the target converter.
@@ -224,6 +223,7 @@ static inline size_t tv_strlen(const typval_T *const tv)
 /// @param  firstargname  Name of the first argument.
 #define TYPVAL_ENCODE_DEFINE_CONV_FUNCTIONS(scope, name, firstargtype, \
                                             firstargname) \
+/* Returns OK or FAIL */ \
 static int name##_convert_one_value(firstargtype firstargname, \
                                     MPConvStack *const mpstack, \
                                     typval_T *const tv, \