feat: Consistent and sensible layout_config (#922)

* feat: Consistent and sensible layout_config

* [docgen] Update doc/telescope.txt
skip-checks: true

* [WIP]: Thu 17 Jun 2021 03:36:44 PM EDT

* [WIP]: Thu 17 Jun 2021 03:38:11 PM EDT

* layout_default -> layout_defaults

* remove options from bug repot

* Conni2461 suggestions: part 1

* [docgen] Update doc/telescope.txt
skip-checks: true

* Conni2461 suggestions: part 2

* [docgen] Update doc/telescope.txt
skip-checks: true

* Linting

* Improve deprecation checks

- Move `layout_defaults` handling to `deprecated.lua`
- Check for "layout keys" outside of `layout_config` on `setup`

* fixup: Just add a few more words

Co-authored-by: Luke Kershaw <35707277+l-kershaw@users.noreply.github.com>
Co-authored-by: Github Actions <actions@github>

lua/telescope/deprecated.lua

@@ -0,0 +1,59 @@
+local log = require "telescope.log"
+
+local deprecated = {}
+
+deprecated.picker_window_options = function(opts)
+  local messages = {}
+
+  -- Deprecated: PR:922, 2021/06/25
+  -- Can be removed in a few weeks.
+
+  if opts.width then
+    table.insert(messages, "'opts.width' is no longer valid. Please use 'layout_config.width' instead")
+  end
+
+  if opts.height then
+    table.insert(messages, "'opts.height' is no longer valid. Please use 'layout_config.height' instead")
+  end
+
+  if opts.results_height then
+    table.insert(messages, "'opts.results_height' is no longer valid. Please see ':help telescope.changelog-922'")
+  end
+
+  if opts.results_width then
+    table.insert(messages,
+      "'opts.results_width' actually didn't do anything. Please see ':help telescope.changelog-922'"
+    )
+  end
+
+  if opts.prompt_position then
+    table.insert(messages,
+      "'opts.prompt_position' is no longer valid. Please use 'layout_config.prompt_position' instead."
+    )
+  end
+
+  if opts.preview_cutoff then
+    table.insert(messages,
+      "'opts.preview_cutoff' is no longer valid. Please use 'layout_config.preview_cutoff' instead."
+    )
+  end
+
+  if #messages > 0 then
+    table.insert(messages, 1, "Deprecated window options. Please see ':help telescope.changelog'")
+    vim.api.nvim_err_write(table.concat(messages, "\n \n   ") .. "\n \nPress <Enter> to continue\n")
+  end
+end
+
+deprecated.layout_configuration = function(user_defaults)
+  if user_defaults.layout_defaults then
+    if user_defaults.layout_config == nil then
+      log.warn "Using 'layout_defaults' in setup() is deprecated. Use 'layout_config' instead."
+      user_defaults.layout_config = user_defaults.layout_defaults
+    else
+      error "Using 'layout_defaults' in setup() is deprecated. Remove this key and use 'layout_config' instead."
+    end
+  end
+  return user_defaults
+end
+
+return deprecated