api metadata: Allow typed container information in api functions

Adapt gendeclarations.lua/msgpack-gen.lua to allow the `ArrayOf(...)` and
`DictionaryOf(...)` types in function headers. These are simple macros that
expand to Array and Dictionary respectively, but the information is kept in the
metadata object, which is useful for building clients in statically typed
languages.

src/nvim/api/buffer.c

@@ -95,12 +95,12 @@ void buffer_del_line(Buffer buffer, Integer index, Error *err)
 /// @param include_end True if the slice includes the `end` parameter
 /// @param[out] err Details of an error that may have occurred
 /// @return An array of lines
-Array buffer_get_slice(Buffer buffer,
-                       Integer start,
-                       Integer end,
-                       Boolean include_start,
-                       Boolean include_end,
-                       Error *err)
+ArrayOf(String) buffer_get_slice(Buffer buffer,
+                                 Integer start,
+                                 Integer end,
+                                 Boolean include_start,
+                                 Boolean include_end,
+                                 Error *err)
 {
   Array rv = ARRAY_DICT_INIT;
   buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -161,7 +161,7 @@ void buffer_set_slice(Buffer buffer,
                       Integer end,
                       Boolean include_start,
                       Boolean include_end,
-                      Array replacement,
+                      ArrayOf(String) replacement,
                       Error *err)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -436,7 +436,10 @@ Boolean buffer_is_valid(Buffer buffer)
 ///        to the end of the buffer.
 /// @param lines An array of lines
 /// @param[out] err Details of an error that may have occurred
-void buffer_insert(Buffer buffer, Integer lnum, Array lines, Error *err)
+void buffer_insert(Buffer buffer,
+                   Integer lnum,
+                   ArrayOf(String) lines,
+                   Error *err)
 {
   buffer_set_slice(buffer, lnum, lnum, false, true, lines, err);
 }
@@ -447,7 +450,7 @@ void buffer_insert(Buffer buffer, Integer lnum, Array lines, Error *err)
 /// @param name The mark's name
 /// @param[out] err Details of an error that may have occurred
 /// @return The (row, col) tuple
-Array buffer_get_mark(Buffer buffer, String name, Error *err)
+ArrayOf(Integer, 2) buffer_get_mark(Buffer buffer, String name, Error *err)
 {
   Array rv = ARRAY_DICT_INIT;
   buf_T *buf = find_buffer_by_handle(buffer, err);

src/nvim/api/private/defs.h

@@ -10,6 +10,11 @@
 #define OBJECT_INIT { .type = kObjectTypeNil }
 #define REMOTE_TYPE(type) typedef uint64_t type
 
+#ifdef INCLUDE_GENERATED_DECLARATIONS
+  #define ArrayOf(...) Array
+  #define DictionaryOf(...) Dictionary
+#endif
+
 // Basic types
 typedef struct {
   char msg[256];

src/nvim/api/tabpage.c

@@ -13,7 +13,7 @@
 /// @param tabpage The tabpage
 /// @param[out] err Details of an error that may have occurred
 /// @return The number of windows in `tabpage`
-Array tabpage_get_windows(Tabpage tabpage, Error *err)
+ArrayOf(Window) tabpage_get_windows(Tabpage tabpage, Error *err)
 {
   Array rv = ARRAY_DICT_INIT;
   tabpage_T *tab = find_tab_by_handle(tabpage, err);

src/nvim/api/vim.c

@@ -149,7 +149,7 @@ Integer vim_strwidth(String str, Error *err)
 /// Returns a list of paths contained in 'runtimepath'
 ///
 /// @return The list of paths
-Array vim_list_runtime_paths(void)
+ArrayOf(String) vim_list_runtime_paths(void)
 {
   Array rv = ARRAY_DICT_INIT;
   uint8_t *rtp = p_rtp;
@@ -321,7 +321,7 @@ void vim_report_error(String str)
 /// Gets the current list of buffer handles
 ///
 /// @return The number of buffers
-Array vim_get_buffers(void)
+ArrayOf(Buffer) vim_get_buffers(void)
 {
   Array rv = ARRAY_DICT_INIT;
   buf_T *b = firstbuf;
@@ -381,7 +381,7 @@ void vim_set_current_buffer(Buffer buffer, Error *err)
 /// Gets the current list of window handles
 ///
 /// @return The number of windows
-Array vim_get_windows(void)
+ArrayOf(Window) vim_get_windows(void)
 {
   Array rv = ARRAY_DICT_INIT;
   tabpage_T *tp;
@@ -437,7 +437,7 @@ void vim_set_current_window(Window window, Error *err)
 /// Gets the current list of tabpage handles
 ///
 /// @return The number of tab pages
-Array vim_get_tabpages(void)
+ArrayOf(Tabpage) vim_get_tabpages(void)
 {
   Array rv = ARRAY_DICT_INIT;
   tabpage_T *tp = first_tabpage;

src/nvim/api/window.c

@@ -33,7 +33,7 @@ Buffer window_get_buffer(Window window, Error *err)
 /// @param window The window handle
 /// @param[out] err Details of an error that may have occurred
 /// @return the (row, col) tuple
-Array window_get_cursor(Window window, Error *err)
+ArrayOf(Integer, 2) window_get_cursor(Window window, Error *err)
 {
   Array rv = ARRAY_DICT_INIT;
   win_T *win = find_window_by_handle(window, err);
@@ -51,7 +51,7 @@ Array window_get_cursor(Window window, Error *err)
 /// @param window The window handle
 /// @param pos the (row, col) tuple representing the new position
 /// @param[out] err Details of an error that may have occurred
-void window_set_cursor(Window window, Array pos, Error *err)
+void window_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
 {
   win_T *win = find_window_by_handle(window, err);
 
@@ -247,7 +247,7 @@ void window_set_option(Window window, String name, Object value, Error *err)
 /// @param window The window handle
 /// @param[out] err Details of an error that may have occurred
 /// @return The (row, col) tuple with the window position
-Array window_get_position(Window window, Error *err)
+ArrayOf(Integer, 2) window_get_position(Window window, Error *err)
 {
   Array rv = ARRAY_DICT_INIT;
   win_T *win = find_window_by_handle(window, err);