refactor(lua): deprecate tbl_flatten

Problem:
Besides being redundant with vim.iter():flatten(), `tbl_flatten` has
these problems:

- Has `tbl_` prefix but only accepts lists.
- Discards some results! Compare the following:
  - iter.flatten():
    ```
    vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()
    ```
  - tbl_flatten:
    ```
    vim.tbl_flatten({1, { { a = 2 } }, { 3 } })
    ```

Solution:
Deprecate tbl_flatten.

Note:
iter:flatten() currently fails ("flatten() requires a list-like table")
on this code from gen_lsp.lua:

    local anonym = vim.iter({ -- remove nil
      anonymous_num > 1 and '' or nil,
      '---@class ' .. anonymous_classname,
    }):flatten():totable()

Should we enhance :flatten() to work for arrays?

1 files changed, 0 insertions, 14 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index de1e432790..eaf61ff3fe 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2285,20 +2285,6 @@ vim.tbl_filter({func}, {t})                                 *vim.tbl_filter()*
     Return: ~
         (`any[]`) Table of filtered values
 
-vim.tbl_flatten({t})                                       *vim.tbl_flatten()*
-    Creates a copy of a list-like table such that any nested tables are
-    "unrolled" and appended to the result.
-
-    Parameters: ~
-      • {t}  (`table`) List-like table
-
-    Return: ~
-        (`table`) Flattened copy of the given list-like table
-
-    See also: ~
-      • From
-        https://github.com/premake/premake-core/blob/master/src/base/table.lua
-
 vim.tbl_get({o}, {...})                                        *vim.tbl_get()*
     Index into a table (first argument) via string keys passed as subsequent
     arguments. Return `nil` if the key does not exist.