vim-patch:02f3eba: runtime(doc): deduplicate getpos(), line(), col(), virtcol()

Move the main description to getpos() and link to that from the other
functions.

closes: vim/vim#14970

https://github.com/vim/vim/commit/02f3ebacfbfa1f892347d7532278f24620e68300

1 files changed, 54 insertions, 59 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index ad057d902b..e9794b444c 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -911,33 +911,31 @@ function vim.fn.cindent(lnum) end
 function vim.fn.clearmatches(win) end
 
 --- The result is a Number, which is the byte index of the column
---- position given with {expr}.  The accepted positions are:
----     .      the cursor position
----     $      the end of the cursor line (the result is the
----       number of bytes in the cursor line plus one)
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     v       In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
+--- position given with {expr}.
+--- For accepted positions see |getpos()|.
 --- Additionally {expr} can be [lnum, col]: a |List| with the line
 --- and column number. Most useful when the column is "$", to get
 --- the last column of a specific line.  When "lnum" or "col" is
 --- out of range then col() returns zero.
+---
 --- With the optional {winid} argument the values are obtained for
 --- that window instead of the current window.
+---
 --- To get the line number use |line()|.  To get both use
 --- |getpos()|.
+---
 --- For the screen column position use |virtcol()|.  For the
 --- character position use |charcol()|.
+---
 --- Note that only marks in the current file can be used.
+---
 --- Examples: >vim
 ---   echo col(".")      " column of cursor
 ---   echo col("$")      " length of cursor line plus one
 ---   echo col("'t")      " column of mark t
 ---   echo col("'" .. markname)  " column of mark markname
---- <The first column is 1.  Returns 0 if {expr} is invalid or when
+--- <
+--- The first column is 1.  Returns 0 if {expr} is invalid or when
 --- the window with ID {winid} is not found.
 --- For an uppercase mark the column may actually be in another
 --- buffer.
@@ -3329,9 +3327,34 @@ function vim.fn.getmousepos() end
 --- @return integer
 function vim.fn.getpid() end
 
---- Get the position for String {expr}.  For possible values of
---- {expr} see |line()|.  For getting the cursor position see
---- |getcurpos()|.
+--- Get the position for String {expr}.
+--- The accepted values for {expr} are:
+---     .      The cursor position.
+---     $      The last line in the current buffer.
+---     'x      Position of mark x (if the mark is not set, 0 is
+---       returned).
+---     w0      First line visible in current window (one if the
+---       display isn't updated, e.g. in silent Ex mode).
+---     w$      Last line visible in current window (this is one
+---       less than "w0" if no lines are visible).
+---     v      When not in Visual mode, returns the cursor
+---       position.  In Visual mode, returns the other end
+---       of the Visual area.  A good way to think about
+---       this is that in Visual mode "v" and "." complement
+---       each other.  While "." refers to the cursor
+---       position, "v" refers to where |v_o| would move the
+---       cursor.  As a result, you can use "v" and "."
+---       together to work on all of a selection in
+---       characterwise Visual mode.  If the cursor is at
+---       the end of a characterwise Visual area, "v" refers
+---       to the start of the same Visual area.  And if the
+---       cursor is at the start of a characterwise Visual
+---       area, "v" refers to the end of the same Visual
+---       area.  "v" differs from |'<| and |'>| in that it's
+---       updated right away.
+--- Note that a mark in another file can be used.  The line number
+--- then applies to another buffer.
+---
 --- The result is a |List| with four numbers:
 ---     [bufnum, lnum, col, off]
 --- "bufnum" is zero, unless a mark like '0 or 'A is used, then it
@@ -3342,19 +3365,24 @@ function vim.fn.getpid() end
 --- it is the offset in screen columns from the start of the
 --- character.  E.g., a position within a <Tab> or after the last
 --- character.
---- Note that for '< and '> Visual mode matters: when it is "V"
---- (visual line mode) the column of '< is zero and the column of
---- '> is a large number equal to |v:maxcol|.
+---
+--- For getting the cursor position see |getcurpos()|.
 --- The column number in the returned List is the byte position
 --- within the line. To get the character position in the line,
 --- use |getcharpos()|.
+---
+--- Note that for '< and '> Visual mode matters: when it is "V"
+--- (visual line mode) the column of '< is zero and the column of
+--- '> is a large number equal to |v:maxcol|.
 --- A very large column number equal to |v:maxcol| can be returned,
 --- in which case it means "after the end of the line".
 --- If {expr} is invalid, returns a list with all zeros.
+---
 --- This can be used to save and restore the position of a mark: >vim
 ---   let save_a_mark = getpos("'a")
 ---   " ...
 ---   call setpos("'a", save_a_mark)
+---
 --- <Also see |getcharpos()|, |getcurpos()| and |setpos()|.
 ---
 --- @param expr string
@@ -4960,39 +4988,16 @@ function vim.fn.libcall(libname, funcname, argument) end
 --- @return any
 function vim.fn.libcallnr(libname, funcname, argument) end
 
---- The result is a Number, which is the line number of the file
---- position given with {expr}.  The {expr} argument is a string.
---- The accepted positions are:
----     .      the cursor position
----     $      the last line in the current buffer
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     w0      first line visible in current window (one if the
----       display isn't updated, e.g. in silent Ex mode)
----     w$      last line visible in current window (this is one
----       less than "w0" if no lines are visible)
----     v      When not in Visual mode, returns the cursor
----       position.  In Visual mode, returns the other end
----       of the Visual area.  A good way to think about
----       this is that in Visual mode "v" and "." complement
----       each other.  While "." refers to the cursor
----       position, "v" refers to where |v_o| would move the
----       cursor.  As a result, you can use "v" and "."
----       together to work on all of a selection in
----       characterwise visual mode.  If the cursor is at
----       the end of a characterwise visual area, "v" refers
----       to the start of the same visual area.  And if the
----       cursor is at the start of a characterwise visual
----       area, "v" refers to the end of the same visual
----       area.  "v" differs from |'<| and |'>| in that it's
----       updated right away.
---- Note that a mark in another file can be used.  The line number
---- then applies to another buffer.
+--- See |getpos()| for accepted positions.
+---
 --- To get the column number use |col()|.  To get both use
 --- |getpos()|.
+---
 --- With the optional {winid} argument the values are obtained for
 --- that window instead of the current window.
+---
 --- Returns 0 for invalid values of {expr} and {winid}.
+---
 --- Examples: >vim
 ---   echo line(".")      " line number of the cursor
 ---   echo line(".", winid)    " idem, in window "winid"
@@ -10410,7 +10415,7 @@ function vim.fn.values(dict) end
 --- set to 8, it returns 8. |conceal| is ignored.
 --- For the byte position use |col()|.
 ---
---- For the use of {expr} see |col()|.
+--- For the use of {expr} see |getpos()| and |col()|.
 ---
 --- When 'virtualedit' is used {expr} can be [lnum, col, off],
 --- where "off" is the offset in screen columns from the start of
@@ -10420,18 +10425,6 @@ function vim.fn.values(dict) end
 --- beyond the end of the line can be returned.  Also see
 --- |'virtualedit'|
 ---
---- The accepted positions are:
----     .      the cursor position
----     $      the end of the cursor line (the result is the
----       number of displayed characters in the cursor line
----       plus one)
----     'x      position of mark x (if the mark is not set, 0 is
----       returned)
----     v       In Visual mode: the start of the Visual area (the
----       cursor is the end).  When not in Visual mode
----       returns the cursor position.  Differs from |'<| in
----       that it's updated right away.
----
 --- If {list} is present and non-zero then virtcol() returns a
 --- List with the first and last screen position occupied by the
 --- character.
@@ -10450,7 +10443,9 @@ function vim.fn.values(dict) end
 ---   " With text "    there", with 't at 'h':
 ---
 ---   echo virtcol("'t")  " returns 6
---- <The first column is 1.  0 or [0, 0] is returned for an error.
+--- <
+--- The first column is 1.  0 or [0, 0] is returned for an error.
+---
 --- A more advanced example that echoes the maximum length of
 --- all lines: >vim
 ---     echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))