docs(builtin): show tag at first line with multiple signatures (#27577)

Problem:
When a function has multiple signatures, putting its tag at the last one
may make one think that's its only signature.

Solution:
When a function has multiple signatures, put its tag at the first one.

2 files changed, 22 insertions, 32 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index fc1c770de7..c6d75ab985 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -965,8 +965,8 @@ ctxset({context} [, {index}])                                         *ctxset()*
 ctxsize()                                                            *ctxsize()*
 		Returns the size of the |context-stack|.
 
-cursor({lnum}, {col} [, {off}])
-cursor({list})                                                        *cursor()*
+cursor({lnum}, {col} [, {off}])                                       *cursor()*
+cursor({list})
 		Positions the cursor at the column (byte count) {col} in the
 		line {lnum}.  The first column is one.
 
@@ -2055,8 +2055,8 @@ get({func}, {what})
 			"args"	The list with arguments
 		Returns zero on error.
 
-getbufinfo([{buf}])
-getbufinfo([{dict}])                                              *getbufinfo()*
+getbufinfo([{buf}])                                               *getbufinfo()*
+getbufinfo([{dict}])
 		Get information about buffers as a List of Dictionaries.
 
 		Without an argument information about all the buffers is
@@ -4310,8 +4310,8 @@ mapnew({expr1}, {expr2})                                              *mapnew()*
 		unchanged.  Items can still be changed by {expr2}, if you
 		don't want that use |deepcopy()| first.
 
-mapset({mode}, {abbr}, {dict})
-mapset({dict})                                                        *mapset()*
+mapset({mode}, {abbr}, {dict})                                        *mapset()*
+mapset({dict})
 		Restore a mapping from a dictionary, possibly returned by
 		|maparg()| or |maplist()|.  A buffer mapping, when dict.buffer
 		is true, is set on the current buffer; it is up to the caller
@@ -5740,9 +5740,9 @@ reg_recording()                                                *reg_recording()*
 		Returns the single letter name of the register being recorded.
 		Returns an empty string when not recording.  See |q|.
 
-reltime()
+reltime()                                                            *reltime()*
 reltime({start})
-reltime({start}, {end})                                              *reltime()*
+reltime({start}, {end})
 		Return an item that represents a time value.  The item is a
 		list with items that depend on the system.
 		The item can be passed to |reltimestr()| to convert it to a
@@ -5787,8 +5787,8 @@ reltimestr({time})                                                *reltimestr()*
 <		Also see |profiling|.
 		If there is an error an empty string is returned
 
-remove({list}, {idx})
-remove({list}, {idx}, {end})                                          *remove()*
+remove({list}, {idx})                                                 *remove()*
+remove({list}, {idx}, {end})
 		Without {end}: Remove the item at {idx} from |List| {list} and
 		return the item.
 		With {end}: Remove items from {idx} to {end} (inclusive) and
@@ -6517,8 +6517,8 @@ setcmdpos({pos})                                                   *setcmdpos()*
 		Returns 0 when successful, 1 when not editing the command
 		line.
 
-setcursorcharpos({lnum}, {col} [, {off}])
-setcursorcharpos({list})                                    *setcursorcharpos()*
+setcursorcharpos({lnum}, {col} [, {off}])                   *setcursorcharpos()*
+setcursorcharpos({list})
 		Same as |cursor()| but uses the specified column number as the
 		character index instead of the byte index in the line.
 
@@ -6944,8 +6944,8 @@ shiftwidth([{col}])                                               *shiftwidth()*
 		'vartabstop' feature. If no {col} argument is given, column 1
 		will be assumed.
 
-sign_define({name} [, {dict}])
-sign_define({list})                                              *sign_define()*
+sign_define({name} [, {dict}])                                   *sign_define()*
+sign_define({list})
 		Define a new sign named {name} or modify the attributes of an
 		existing sign.  This is similar to the |:sign-define| command.
 
@@ -7212,8 +7212,8 @@ sign_placelist({list})                                        *sign_placelist()*
 				\ ])
 <
 
-sign_undefine([{name}])
-sign_undefine({list})                                          *sign_undefine()*
+sign_undefine([{name}])                                        *sign_undefine()*
+sign_undefine({list})
 		Deletes a previously defined sign {name}. This is similar to
 		the |:sign-undefine| command. If {name} is not supplied, then
 		deletes all the defined signs.
diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua
index 78fc1c7d4f..b7f17a2d58 100755
--- a/scripts/gen_eval_files.lua
+++ b/scripts/gen_eval_files.lua
@@ -411,9 +411,6 @@ local function render_eval_meta(f, fun, write)
   write(render_fun_sig(funname, params))
 end
 
---- @type table<string,true>
-local rendered_tags = {}
-
 --- @param name string
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
@@ -455,24 +452,17 @@ local function render_eval_doc(f, fun, write)
     return
   end
 
-  local desc = fun.desc
-
-  if not desc then
+  if f:find('__%d+$') then
     write(fun.signature)
-    return
+  else
+    render_sig_and_tag(fun.name or f, fun, write)
   end
 
-  local name = fun.name or f
-
-  if rendered_tags[name] then
-    write(fun.signature)
-  else
-    render_sig_and_tag(name, fun, write)
-    rendered_tags[name] = true
+  if not fun.desc then
+    return
   end
 
-  desc = vim.trim(desc)
-  local desc_l = split(desc)
+  local desc_l = split(vim.trim(fun.desc))
   for _, l in ipairs(desc_l) do
     l = l:gsub('^      ', '')
     if vim.startswith(l, '<') and not l:match('^<[^ \t]+>') then