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?

runtime/lua/vim/shared.lua

@@ -544,6 +544,7 @@ function vim.list_extend(dst, src, start, finish)
   return dst
 end
 
+--- @deprecated
 --- Creates a copy of a list-like table such that any nested tables are
 --- "unrolled" and appended to the result.
 ---