API/nvim_set_keymap: minor cleanup

ref #9924

4 files changed, 72 insertions, 76 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 61e042ef40..9a5ffecad4 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -577,9 +577,11 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
   return keymap_array(mode, buf);
 }
 
-/// Like |nvim_set_keymap|, but for a specific buffer.
+/// Sets a buffer-local |mapping| for the given mode.
 ///
-/// @param  buffer  Buffer handle, or 0 for the current buffer.
+/// @see |nvim_set_keymap()|
+///
+/// @param  buffer  Buffer handle, or 0 for current buffer
 void nvim_buf_set_keymap(Buffer buffer, String mode, String lhs, String rhs,
                          Dictionary opts, Error *err)
   FUNC_API_SINCE(6)
@@ -587,9 +589,11 @@ void nvim_buf_set_keymap(Buffer buffer, String mode, String lhs, String rhs,
   modify_keymap(buffer, false, mode, lhs, rhs, opts, err);
 }
 
-/// Like |nvim_del_keymap|, but for a specific buffer.
+/// Unmaps a buffer-local |mapping| for the given mode.
 ///
-/// @param  buffer  Buffer handle, or 0 for the current buffer.
+/// @see |nvim_del_keymap()|
+///
+/// @param  buffer  Buffer handle, or 0 for current buffer
 void nvim_buf_del_keymap(Buffer buffer, String mode, String lhs, Error *err)
   FUNC_API_SINCE(6)
 {
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index aa9b3f5f18..2bd51f71d7 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -770,7 +770,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
   MapArguments parsed_args;
   memset(&parsed_args, 0, sizeof(parsed_args));
   if (parse_keymap_opts(opts, &parsed_args, err)) {
-    goto FAIL_AND_FREE;
+    goto fail_and_free;
   }
   parsed_args.buffer = !global;
 
@@ -782,14 +782,14 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     err_msg = "LHS exceeds maximum map length: %s";
     err_arg = lhs.data;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
   if (mode.size > 1) {
     err_msg = "Shortname is too long: %s";
     err_arg = mode.data;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
   int mode_val;  // integer value of the mapping mode, to be passed to do_map()
   char_u *p = (char_u *)((mode.size) ? mode.data : "m");
@@ -804,7 +804,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
         err_msg = "Invalid mode shortname: %s";
         err_arg = (char *)p;
         err_type = kErrorTypeValidation;
-        goto FAIL_WITH_MESSAGE;
+        goto fail_with_message;
       }
     }
   }
@@ -813,7 +813,7 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     err_msg = "Invalid (empty) LHS";
     err_arg = "";
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
   bool is_noremap = parsed_args.noremap;
@@ -829,16 +829,16 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
       err_msg = "Parsing of nonempty RHS failed: %s";
       err_arg = rhs.data;
       err_type = kErrorTypeException;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
   } else if (is_unmap && parsed_args.rhs_len) {
     err_msg = "Gave nonempty RHS in unmap command: %s";
     err_arg = (char *)parsed_args.rhs;
     err_type = kErrorTypeValidation;
-    goto FAIL_WITH_MESSAGE;
+    goto fail_with_message;
   }
 
-  // buf_do_map_explicit reads noremap/unmap as its own argument
+  // buf_do_map() reads noremap/unmap as its own argument.
   int maptype_val = 0;
   if (is_unmap) {
     maptype_val = 1;
@@ -846,23 +846,22 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
     maptype_val = 2;
   }
 
-  switch (buf_do_map_explicit(maptype_val, &parsed_args, mode_val,
-                              0, target_buf)) {
+  switch (buf_do_map(maptype_val, &parsed_args, mode_val, 0, target_buf)) {
     case 0:
       break;
     case 1:
       api_set_error(err, kErrorTypeException, (char *)e_invarg, 0);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     case 2:
       api_set_error(err, kErrorTypeException, (char *)e_nomap, 0);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     case 5:
       api_set_error(err, kErrorTypeException,
                     "E227: mapping already exists for %s", parsed_args.lhs);
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
     default:
       assert(false && "Unrecognized return code!");
-      goto FAIL_AND_FREE;
+      goto fail_and_free;
   }  // switch
 
   xfree(lhs_buf);
@@ -872,10 +871,10 @@ void modify_keymap(Buffer buffer, bool is_unmap, String mode, String lhs,
 
   return;
 
-FAIL_WITH_MESSAGE:
+fail_with_message:
   api_set_error(err, err_type, err_msg, err_arg);
 
-FAIL_AND_FREE:
+fail_and_free:
   xfree(lhs_buf);
   xfree(rhs_buf);
   xfree(parsed_args.rhs);
@@ -913,7 +912,7 @@ Integer parse_keymap_opts(Dictionary opts, MapArguments *out, Error *err)
       err_msg = "Gave non-boolean value for an opt: %s";
       err_arg = optname;
       err_type = kErrorTypeValidation;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
 
     bool was_valid_opt = false;
@@ -961,13 +960,13 @@ Integer parse_keymap_opts(Dictionary opts, MapArguments *out, Error *err)
       err_msg = "Invalid key: %s";
       err_arg = optname;
       err_type = kErrorTypeValidation;
-      goto FAIL_WITH_MESSAGE;
+      goto fail_with_message;
     }
   }  // for
 
   return 0;
 
-FAIL_WITH_MESSAGE:
+fail_with_message:
   api_set_error(err, err_type, err_msg, err_arg);
   return 1;
 }
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 53aad1fe39..b8c863704a 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1264,29 +1264,28 @@ ArrayOf(Dictionary) nvim_get_keymap(String mode)
 
 /// Sets a global |mapping| for the given mode.
 ///
-/// To set a buffer-local mapping, use |nvim_buf_set_keymap|.
+/// To set a buffer-local mapping, use |nvim_buf_set_keymap()|.
 ///
-/// Unlike ordinary Ex mode |:map| commands, special characters like literal
-/// spaces and newlines are treated as an actual part of the {lhs} or {rhs}.
-/// An empty {rhs} is treated like a |<Nop>|. |keycodes| are still replaced as
-/// usual.
+/// Unlike |:map|, leading/trailing whitespace is accepted as part of the {lhs}
+/// or {rhs}. Empty {rhs} is |<Nop>|. |keycodes| are replaced as usual.
 ///
-/// `call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})`
-///
-/// Is equivalent to,
+/// Example:
+/// <pre>
+///     call nvim_set_keymap('n', ' <NL>', '', {'nowait': v:true})
+/// </pre>
 ///
-/// `nmap <nowait> <Space><NL> <Nop>`
+/// is equivalent to:
+/// <pre>
+///     nmap <nowait> <Space><NL> <Nop>
+/// </pre>
 ///
-/// @param  mode  Mode short-name (the first character of an map command,
-///               e.g. "n", "i", "v", "x", etc.) OR the string "!" (for
-///               |:map!|). |:map| can be represented with a single space " ",
-///               an empty string, or "m".
+/// @param  mode  Mode short-name (map command prefix: "n", "i", "v", "x", …)
+///               or "!" for |:map!|, or empty string for |:map|.
 /// @param  lhs   Left-hand-side |{lhs}| of the mapping.
 /// @param  rhs   Right-hand-side |{rhs}| of the mapping.
-/// @param  opts  |dict| of optional parameters. Accepts all |:map-arguments|
-///               as keys excluding |<buffer>| but also including |noremap|.
-///               Values should all be Booleans. Unrecognized keys will result
-///               in an error.
+/// @param  opts  Optional parameters map. Accepts all |:map-arguments|
+///               as keys excluding |<buffer>| but including |noremap|.
+///               Values are Booleans. Unknown key is an error.
 /// @param[out]   err   Error details, if any.
 void nvim_set_keymap(String mode, String lhs, String rhs,
                      Dictionary opts, Error *err)
@@ -1295,14 +1294,11 @@ void nvim_set_keymap(String mode, String lhs, String rhs,
   modify_keymap(-1, false, mode, lhs, rhs, opts, err);
 }
 
-/// Unmap a global |mapping| for the given mode.
+/// Unmaps a global |mapping| for the given mode.
 ///
-/// To unmap a buffer-local mapping, use |nvim_buf_del_keymap|.
+/// To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.
 ///
-/// Arguments are handled like |nvim_set_keymap|. Like with ordinary |:unmap|
-/// commands (and `nvim_set_keymap`), the given {lhs} is interpreted literally:
-/// for instance, trailing whitespace is treated as part of the {lhs}.
-/// |keycodes| are still replaced as usual.
+/// @see |nvim_set_keymap()|
 void nvim_del_keymap(String mode, String lhs, Error *err)
   FUNC_API_SINCE(6)
 {
diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c
index af9861d665..f8c7dc613b 100644
--- a/src/nvim/getchar.c
+++ b/src/nvim/getchar.c
@@ -2683,15 +2683,18 @@ int str_to_mapargs(const char_u *strargs, bool is_unmap, MapArguments *mapargs)
   return 0;
 }
 
-/// Actually set/unset a mapping or abbreviation.
+/// Sets or removes a mapping or abbreviation in buffer `buf`.
 ///
-/// Parameters are like @ref buf_do_map unless otherwise noted.
+/// @param maptype    @see do_map
 /// @param args  Fully parsed and "preprocessed" arguments for the
 ///              (un)map/abbrev command. Termcodes should have already been
 ///              replaced; whitespace, `<` and `>` signs, etc. in {lhs} and
 ///              {rhs} are assumed to be literal components of the mapping.
-int buf_do_map_explicit(int maptype, MapArguments *args, int mode,
-                        bool is_abbrev, buf_T *buf)
+/// @param mode       @see do_map
+/// @param is_abbrev  @see do_map
+/// @param buf        Target Buffer
+int buf_do_map(int maptype, MapArguments *args, int mode, bool is_abbrev,
+               buf_T *buf)
 {
   mapblock_T  *mp, **mpp;
   char_u      *p;
@@ -3030,31 +3033,6 @@ theend:
   return retval;
 }
 
-/// Like @ref do_map, but you can specify the target buffer.
-int buf_do_map(int maptype, char_u *arg, int mode, bool is_abbrev, buf_T *buf)
-{
-  MapArguments parsed_args;
-  int result = str_to_mapargs(arg, maptype == 1, &parsed_args);
-  switch (result) {
-    case 0:
-      break;
-    case 1:
-      result = 1;  // invalid arguments
-      goto FREE_AND_RETURN;
-    default:
-      assert(false && "Unknown return code from str_to_mapargs!");
-      result = -1;
-      goto FREE_AND_RETURN;
-  }  // switch
-
-  result = buf_do_map_explicit(maptype, &parsed_args, mode, is_abbrev, buf);
-
-FREE_AND_RETURN:
-  xfree(parsed_args.rhs);
-  xfree(parsed_args.orig_rhs);
-  return result;
-}
-
 
 /// Set or remove a mapping or an abbreviation in the current buffer, OR
 /// display (matching) mappings/abbreviations.
@@ -3104,7 +3082,26 @@ FREE_AND_RETURN:
 ///
 int do_map(int maptype, char_u *arg, int mode, bool is_abbrev)
 {
-  return buf_do_map(maptype, arg, mode, is_abbrev, curbuf);
+  MapArguments parsed_args;
+  int result = str_to_mapargs(arg, maptype == 1, &parsed_args);
+  switch (result) {
+    case 0:
+      break;
+    case 1:
+      result = 1;  // invalid arguments
+      goto free_and_return;
+    default:
+      assert(false && "Unknown return code from str_to_mapargs!");
+      result = -1;
+      goto free_and_return;
+  }  // switch
+
+  result = buf_do_map(maptype, &parsed_args, mode, is_abbrev, curbuf);
+
+free_and_return:
+  xfree(parsed_args.rhs);
+  xfree(parsed_args.orig_rhs);
+  return result;
 }
 
 /*