menu_get(): doc

5 files changed, 48 insertions, 47 deletions

diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 3a27b2d7a0..b68c70bf9f 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -5509,43 +5509,48 @@ max({expr})	Return the maximum value of all items in {expr}.
                 an error.  An empty |List| or |Dictionary| results in zero.
 
 menu_get({path}, {modes})				*menu_get()*
-		Returns a |Dictionary| with all the submenu of {path} (set to 
-		an empty string to match all menus). Only the commands matching {modes} are 
-		returned ('a' for all, 'i' for insert see |creating-menus|).
+		Returns a |List| of |Dictionaries| describing |menus| (defined
+		by |:menu|, |:amenu|, etc.).
+		{path} limits the result to a subtree of the menu hierarchy
+		(empty string matches all menus). E.g. to get items in the
+		"File" menu subtree: >
+			:echo menu_get('File','')
+<
+		{modes} is a string of zero or more modes (see |maparg()| or
+		|creating-menus| for the list of modes). "a" means "all".
 
-    For instance, executing:
->
+		For example: >
 			nnoremenu &Test.Test inormal
 			inoremenu Test.Test insert
 			vnoremenu Test.Test x
 			echo menu_get("")
 <
-should produce an output with a similar structure:
+		returns something like this:
 >
-	[ {
-		"hidden": 0,
-		"name": "Test",
-		"priority": 500,
-		"shortcut": 84,
-		"submenus": [ {
-			"hidden": 0,
-			"mappings": {
-				i": {
-					"enabled": 1,
-					"noremap": 1,
-					"rhs": "insert",
-					"sid": 1,
-					"silent": 0
-				},
-				n": { ... },
-				s": { ... },
-				v": { ... }
-			},
-			"name": "Test",
-			"priority": 500,
-			"shortcut": 0
-		} ]
-	} ]
+			[ {
+			  "hidden": 0,
+			  "name": "Test",
+			  "priority": 500,
+			  "shortcut": 84,
+			  "submenus": [ {
+			    "hidden": 0,
+			    "mappings": {
+			      i": {
+				"enabled": 1,
+				"noremap": 1,
+				"rhs": "insert",
+				"sid": 1,
+				"silent": 0
+			      },
+			      n": { ... },
+			      s": { ... },
+			      v": { ... }
+			    },
+			    "name": "Test",
+			    "priority": 500,
+			    "shortcut": 0
+			  } ]
+			} ]
 <
 
 							*min()*
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 5801da1132..270e958609 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -127,6 +127,7 @@ Functions:
   |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
   |dictwatcherdel()|
   |execute()| works with |:redir|
+  |menu_get()|
   |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
 
 Events:
diff --git a/src/nvim/mbyte.c b/src/nvim/mbyte.c
index 4440300640..3fad6c789d 100644
--- a/src/nvim/mbyte.c
+++ b/src/nvim/mbyte.c
@@ -936,8 +936,7 @@ int utf_char2len(int c)
 ///
 /// @param c character to convert to \p buf
 /// @param[out] buf UTF-8 string generated from \p c, does not add \0
-/// @return the number of bytes (between 1 and 6)
-/// @note This does not include composing characters.
+/// @return Number of bytes (1-6). Does not include composing characters.
 int utf_char2bytes(int c, char_u *const buf)
 {
   if (c < 0x80) {               /* 7 bits */
diff --git a/src/nvim/menu.c b/src/nvim/menu.c
index 91b615be30..a498916e5e 100644
--- a/src/nvim/menu.c
+++ b/src/nvim/menu.c
@@ -91,11 +91,9 @@ ex_menu(exarg_T *eap)
 
 
   // Locate an optional "icon=filename" argument
-  // Kept just the command parsing  from vim for compativility but no further
-  // processing is done
+  // TODO(nvim): Currently this is only parsed. Should expose it to UIs.
   if (STRNCMP(arg, "icon=", 5) == 0) {
     arg += 5;
-    // icon = arg;
     while (*arg != NUL && *arg != ' ') {
       if (*arg == '\\')
         STRMOVE(arg, arg + 1);
@@ -1138,15 +1136,15 @@ static bool menu_namecmp(const char_u *const name, const char_u *const mname)
 }
 
 
-/// converts a string into a combination of \ref MENU_MODES
+/// Returns the \ref MENU_MODES specified by menu command `cmd`.
 ///  (eg :menu! returns MENU_CMDLINE_MODE | MENU_INSERT_MODE)
 ///
-/// @param[in] cmd a string like 'n' (normal) or 'a' (all)
-/// @param[in] forceit Was there a "!" after the command?
-/// @param[out] If "noremap" is not NULL, then the flag it points to is set
-/// according to whether the command is a "nore" command.
-/// @param[out] unmenu is not NULL, then the flag it points to is set according
-/// to whether the command is an "unmenu" command.
+/// @param[in] cmd      string like "nmenu", "vmenu", etc.
+/// @param[in] forceit  bang (!) was given after the command
+/// @param[out] noremap If not NULL, the flag it points to is set according
+///                     to whether the command is a "nore" command.
+/// @param[out] unmenu  If not NULL, the flag it points to is set according
+///                     to whether the command is an "unmenu" command.
 int
 get_menu_cmd_modes(
     const char_u * cmd,
diff --git a/test/functional/ex_cmds/menu_spec.lua b/test/functional/ex_cmds/menu_spec.lua
index eca45efcf1..55da8da8dc 100644
--- a/test/functional/ex_cmds/menu_spec.lua
+++ b/test/functional/ex_cmds/menu_spec.lua
@@ -78,12 +78,10 @@ describe('menu_get', function()
     command('cnoremenu Edit.Paste <C-R>"')
   end)
 
-  it('no path, all modes', function()
+  it("path='', modes='a'", function()
     local m = funcs.menu_get("","a");
-    -- You can use the following to print the expected table
-    -- and regenerate the tests:
-    -- local pretty = require('pl.pretty');
-    -- print(pretty.dump(m))
+    -- HINT: To print the expected table and regenerate the tests:
+    -- print(require('pl.pretty').dump(m))
     local expected = {
       {
         shortcut = "T",