Move documentation from function declarations to definitions

Uses a perl script to move it (scripts/movedocs.pl)

1 files changed, 114 insertions, 7 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 39e2c32d6d..a1aa6b2d79 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -22,20 +22,20 @@
 
 #define LINE_BUFFER_SIZE 4096
 
-/// Writes a message to vim output or error buffer. The string is split
-/// and flushed after each newline. Incomplete lines are kept for writing
-/// later.
-///
-/// @param message The message to write
-/// @param to_err True if it should be treated as an error message(use
-///        `emsg` instead of `msg` to print each line)
 static void write_msg(String message, bool to_err);
 
+/// Send keys to vim input buffer, simulating user input.
+///
+/// @param str The keys to send
 void vim_push_keys(String str)
 {
   abort();
 }
 
+/// Executes an ex-mode command str
+///
+/// @param str The command str
+/// @param[out] err Details of an error that may have occurred
 void vim_command(String str, Error *err)
 {
   // We still use 0-terminated strings, so we must convert.
@@ -48,6 +48,13 @@ void vim_command(String str, Error *err)
   try_end(err);
 }
 
+/// Evaluates the expression str using the vim internal expression
+/// evaluator (see |expression|).
+/// Dictionaries and lists are recursively expanded.
+///
+/// @param str The expression str
+/// @param[out] err Details of an error that may have occurred
+/// @return The expanded object
 Object vim_eval(String str, Error *err)
 {
   Object rv;
@@ -67,6 +74,12 @@ Object vim_eval(String str, Error *err)
   return rv;
 }
 
+/// Calculates the number of display cells `str` occupies, tab is counted as
+/// one cell.
+///
+/// @param str Some text
+/// @param[out] err Details of an error that may have occurred
+/// @return The number of cells
 Integer vim_strwidth(String str, Error *err)
 {
   if (str.size > INT_MAX) {
@@ -80,6 +93,9 @@ Integer vim_strwidth(String str, Error *err)
   return rv;
 }
 
+/// Returns a list of paths contained in 'runtimepath'
+///
+/// @return The list of paths
 StringArray vim_list_runtime_paths(void)
 {
   StringArray rv = ARRAY_DICT_INIT;
@@ -117,6 +133,10 @@ StringArray vim_list_runtime_paths(void)
   return rv;
 }
 
+/// Changes vim working directory
+///
+/// @param dir The new working directory
+/// @param[out] err Details of an error that may have occurred
 void vim_change_directory(String dir, Error *err)
 {
   if (dir.size >= MAXPATHL) {
@@ -141,56 +161,102 @@ void vim_change_directory(String dir, Error *err)
   try_end(err);
 }
 
+/// Return the current line
+///
+/// @param[out] err Details of an error that may have occurred
+/// @return The current line string
 String vim_get_current_line(Error *err)
 {
   return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
 }
 
+/// Sets the current line
+///
+/// @param line The line contents
+/// @param[out] err Details of an error that may have occurred
 void vim_set_current_line(String line, Error *err)
 {
   buffer_set_line(curbuf->handle, curwin->w_cursor.lnum - 1, line, err);
 }
 
+/// Delete the current line
+///
+/// @param[out] err Details of an error that may have occurred
 void vim_del_current_line(Error *err)
 {
   buffer_del_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
 }
 
+/// Gets a global variable
+///
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
 Object vim_get_var(String name, Error *err)
 {
   return dict_get_value(&globvardict, name, err);
 }
 
+/// Sets a global variable. Passing 'nil' as value deletes the variable.
+///
+/// @param name The variable name
+/// @param value The variable value
+/// @param[out] err Details of an error that may have occurred
+/// @return the old value if any
 Object vim_set_var(String name, Object value, Error *err)
 {
   return dict_set_value(&globvardict, name, value, err);
 }
 
+/// Gets a vim variable
+///
+/// @param name The variable name
+/// @param[out] err Details of an error that may have occurred
+/// @return The variable value
 Object vim_get_vvar(String name, Error *err)
 {
   return dict_get_value(&vimvardict, name, err);
 }
 
+/// Get an option value string
+///
+/// @param name The option name
+/// @param[out] err Details of an error that may have occurred
+/// @return The option value
 Object vim_get_option(String name, Error *err)
 {
   return get_option_from(NULL, SREQ_GLOBAL, name, err);
 }
 
+/// Sets an option value
+///
+/// @param name The option name
+/// @param value The new option value
+/// @param[out] err Details of an error that may have occurred
 void vim_set_option(String name, Object value, Error *err)
 {
   set_option_to(NULL, SREQ_GLOBAL, name, value, err);
 }
 
+/// Write a message to vim output buffer
+///
+/// @param str The message
 void vim_out_write(String str)
 {
   write_msg(str, false);
 }
 
+/// Write a message to vim error buffer
+///
+/// @param str The message
 void vim_err_write(String str)
 {
   write_msg(str, true);
 }
 
+/// Gets the current list of buffer handles
+///
+/// @return The number of buffers
 BufferArray vim_get_buffers(void)
 {
   BufferArray rv = ARRAY_DICT_INIT;
@@ -213,11 +279,18 @@ BufferArray vim_get_buffers(void)
   return rv;
 }
 
+/// Return the current buffer
+///
+/// @reqturn The buffer handle
 Buffer vim_get_current_buffer(void)
 {
   return curbuf->handle;
 }
 
+/// Sets the current buffer
+///
+/// @param id The buffer handle
+/// @param[out] err Details of an error that may have occurred
 void vim_set_current_buffer(Buffer buffer, Error *err)
 {
   buf_T *buf = find_buffer(buffer, err);
@@ -241,6 +314,9 @@ void vim_set_current_buffer(Buffer buffer, Error *err)
   try_end(err);
 }
 
+/// Gets the current list of window handles
+///
+/// @return The number of windows
 WindowArray vim_get_windows(void)
 {
   WindowArray rv = ARRAY_DICT_INIT;
@@ -261,11 +337,17 @@ WindowArray vim_get_windows(void)
   return rv;
 }
 
+/// Return the current window
+///
+/// @return The window handle
 Window vim_get_current_window(void)
 {
   return curwin->handle;
 }
 
+/// Sets the current window
+///
+/// @param handle The window handle
 void vim_set_current_window(Window window, Error *err)
 {
   win_T *win = find_window(window, err);
@@ -288,6 +370,9 @@ void vim_set_current_window(Window window, Error *err)
   try_end(err);
 }
 
+/// Gets the current list of tabpage handles
+///
+/// @return The number of tab pages
 TabpageArray vim_get_tabpages(void)
 {
   TabpageArray rv = ARRAY_DICT_INIT;
@@ -310,11 +395,18 @@ TabpageArray vim_get_tabpages(void)
   return rv;
 }
 
+/// Return the current tab page
+///
+/// @return The tab page handle
 Tabpage vim_get_current_tabpage(void)
 {
   return curtab->handle;
 }
 
+/// Sets the current tab page
+///
+/// @param handle The tab page handle
+/// @param[out] err Details of an error that may have occurred
 void vim_set_current_tabpage(Tabpage tabpage, Error *err)
 {
   tabpage_T *tp = find_tab(tabpage, err);
@@ -328,6 +420,10 @@ void vim_set_current_tabpage(Tabpage tabpage, Error *err)
   try_end(err);
 }
 
+/// Subscribes to event broadcasts
+///
+/// @param channel_id The channel id(passed automatically by the dispatcher)
+/// @param event The event type string
 void vim_subscribe(uint64_t channel_id, String event)
 {
   size_t length = (event.size < EVENT_MAXLEN ? event.size : EVENT_MAXLEN);
@@ -337,6 +433,10 @@ void vim_subscribe(uint64_t channel_id, String event)
   channel_subscribe(channel_id, e);
 }
 
+/// Unsubscribes to event broadcasts
+///
+/// @param channel_id The channel id(passed automatically by the dispatcher)
+/// @param event The event type string
 void vim_unsubscribe(uint64_t channel_id, String event)
 {
   size_t length = (event.size < EVENT_MAXLEN ? event.size : EVENT_MAXLEN);
@@ -346,6 +446,13 @@ void vim_unsubscribe(uint64_t channel_id, String event)
   channel_unsubscribe(channel_id, e);
 }
 
+/// Writes a message to vim output or error buffer. The string is split
+/// and flushed after each newline. Incomplete lines are kept for writing
+/// later.
+///
+/// @param message The message to write
+/// @param to_err True if it should be treated as an error message(use
+///        `emsg` instead of `msg` to print each line)
 static void write_msg(String message, bool to_err)
 {
   static int pos = 0;