docs: clarify lazyloading, mention config types (#1734)

Author: pynappo

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -78,6 +78,9 @@ body:
                 "MunifTanjim/nui.nvim",
                 -- { "3rd/image.nvim", opts = {} }, -- Optional image support
               },
+              lazy = false,
+              ---@module "neo-tree"
+              ---@type neotree.Config?
               opts = {
                 -- fill any relevant options here
               },

README.md

@@ -56,6 +56,10 @@ so we can fix it.
 
 ## Minimal Quickstart
 
+> [!NOTE]
+> You do not need to call `require('neo-tree').setup({ ... })` for Neo-tree to work. `setup()` is only used for
+> configuration.
+
 #### Minimal Example for Lazy:
 ```lua
 {
@@ -66,7 +70,13 @@ so we can fix it.
     "nvim-tree/nvim-web-devicons", -- not strictly required, but recommended
     "MunifTanjim/nui.nvim",
     -- {"3rd/image.nvim", opts = {}}, -- Optional image support in preview window: See `# Preview Mode` for more information
-  }
+  },
+  lazy = false, -- neo-tree will lazily load itself
+  ---@module "neo-tree"
+  ---@type neotree.Config?
+  opts = {
+    -- fill any relevant options here
+  },
 }
 ```
 
@@ -142,12 +152,17 @@ return {
         end,
       },
     },
+    lazy = false,
+    -----Instead of using `config`, you can use `opts` instead, if you'd like:
+    -----@module "neo-tree"
+    -----@type neotree.Config
+    --opts = {},
     config = function()
       -- If you want icons for diagnostic errors, you'll need to define them somewhere:
-      vim.fn.sign_define("DiagnosticSignError", { text = " ", texthl = "DiagnosticSignError" })
-      vim.fn.sign_define("DiagnosticSignWarn", { text = " ", texthl = "DiagnosticSignWarn" })
-      vim.fn.sign_define("DiagnosticSignInfo", { text = " ", texthl = "DiagnosticSignInfo" })
-      vim.fn.sign_define("DiagnosticSignHint", { text = "󰌵", texthl = "DiagnosticSignHint" })
+      -- vim.fn.sign_define("DiagnosticSignError", { text = " ", texthl = "DiagnosticSignError" })
+      -- vim.fn.sign_define("DiagnosticSignWarn", { text = " ", texthl = "DiagnosticSignWarn" })
+      -- vim.fn.sign_define("DiagnosticSignInfo", { text = " ", texthl = "DiagnosticSignInfo" })
+      -- vim.fn.sign_define("DiagnosticSignHint", { text = "󰌵", texthl = "DiagnosticSignHint" })
 
       require("neo-tree").setup({
         close_if_last_window = false, -- Close Neo-tree if it is the last window left in the tab

doc/neo-tree.txt

@@ -784,6 +784,28 @@ commented default config in your current file. Even if you don't want to use
 that config as your starting point, you still may want to dump it to a blank
 lua file just to read it as documentation.
 
+NOTE: Neo-tree has type annotations for its configuration. If you have a Lua
+language server that supports EmmyLua/LuaCATS annotations, you can use
+`neotree.Config`, for example:
+
+>lua
+    -- if using lazy.nvim:
+    {
+      "nvim-neo-tree/neo-tree.nvim",
+      dependencies = {
+        "nvim-lua/plenary.nvim",
+        "nvim-tree/nvim-web-devicons",
+        "MunifTanjim/nui.nvim",
+        -- { "3rd/image.nvim", opts = {} }, -- Optional image support
+      },
+      lazy = false, -- neo-tree lazy-loads itself
+      ---@module "neo-tree"
+      ---@type neotree.Config?
+      -- opts = {
+      --   -- fill any relevant options here
+      -- },
+    }
+<
 
 SOURCE SELECTOR                                       *neo-tree-source-selector*