From 9891e326224b84de169f6ba5cdeb467fdb91096e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 5 Jul 2024 07:31:21 +0000 Subject: [PATCH] chore(build): auto-generate docs --- README.vim.md | 60 +++++++++++++++++++++++++++++++++++++++++------ doc/lazy.nvim.txt | 35 +++++++++++++++++---------- 2 files changed, 75 insertions(+), 20 deletions(-) diff --git a/README.vim.md b/README.vim.md index 52788ee..1cabcf3 100644 --- a/README.vim.md +++ b/README.vim.md @@ -242,13 +242,36 @@ A valid spec should define one of `[1]`, `dir` or `url`. ## Spec Setup -| Property | Type | Description | -| ---------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup | -| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` | -| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. | -| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` | -| **build** | `fun(LazyPlugin)` or `string` or `false` or a list of build commands | `build` is executed when a plugin is installed or updated. See [Building](/developers#building) for more information. | +| Property | Type | Description | +| ---------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **init** | `fun(LazyPlugin)` | `init` functions are always executed during. Mostly useful for setting `vim.g.*` configuration used by **Vim** plugins startup | +| **opts** | `table` or `fun(LazyPlugin, opts:table)` | `opts` should be a table (will be merged with parent specs), return a table (replaces parent specs) or should change a table. The table will be passed to the `Plugin.config()` function. Setting this value will imply `Plugin.config()` | +| **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. _(`opts` is the recommended way to configure plugins)_. | +| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` | +| **build** | `fun(LazyPlugin)` or `string` or `false` or a list of build commands | `build` is executed when a plugin is installed or updated. See [Building](/developers#building) for more information. | + +Always use `opts` instead of `config` when possible. `config` is almost never needed. + +:::tip[GOOD] + +```lua +{ "folke/todo-comments.nvim", opts = {} }, +``` + +::: + +:::danger[BAD] + +```lua +{ + "folke/todo-comments.nvim", + config = function() + require("todo-comments").setup({}) + end, +}, +``` + +::: ## Spec Lazy Loading @@ -1053,6 +1076,29 @@ To make it easier for users to install your plugin, you can include a [package s { "nvim-lua/plenary.nvim", lazy = true } ``` +- Always use `opts` instead of `config` when possible. `config` is almost never needed. + + :::tip[GOOD] + + ```lua + { "folke/todo-comments.nvim", opts = {} }, + ``` + + ::: + + :::danger[BAD] + + ```lua + { + "folke/todo-comments.nvim", + config = function() + require("todo-comments").setup({}) + end, + }, + ``` + + ::: + - Only use `dependencies` if a plugin needs the dep to be installed **AND** loaded. Lua plugins/libraries are automatically loaded when they are `require()`d, so they don't need to be in `dependencies`. diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt index ccf4829..73bd0ae 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -291,23 +291,25 @@ SPEC LOADING *lazy.nvim-🔌-plugin-spec-spec-loading* SPEC SETUP *lazy.nvim-🔌-plugin-spec-spec-setup* - --------------------------------------------------------------------------------------------------- + -------------------------------------------------------------------------------------------------- Property Type Description - ---------- ----------------------------- ---------------------------------------------------------- - init fun(LazyPlugin) init functions are always executed during startup + ---------- ----------------------------- --------------------------------------------------------- + init fun(LazyPlugin) init functions are always executed during. Mostly useful + for setting vim.g.* configuration used by Vim plugins + startup - opts table or opts should be a table (will be merged with parent specs), - fun(LazyPlugin, opts:table) return a table (replaces parent specs) or should change a - table. The table will be passed to the Plugin.config() - function. Setting this value will imply Plugin.config() + opts table or opts should be a table (will be merged with parent + fun(LazyPlugin, opts:table) specs), return a table (replaces parent specs) or should + change a table. The table will be passed to the + Plugin.config() function. Setting this value will imply + Plugin.config() config fun(LazyPlugin, opts:table) config is executed when the plugin loads. The default or true implementation will automatically run - require(MAIN).setup(opts) if opts or config = true is set. - Lazy uses several heuristics to determine the plugin’s - MAIN module automatically based on the plugin’s name. See - also opts. To use the default implementation without opts - set config to true. + require(MAIN).setup(opts) if opts or config = true is + set. Lazy uses several heuristics to determine the + plugin’s MAIN module automatically based on the plugin’s + name. (opts is the recommended way to configure plugins). main string? You can specify the main module to use for config() and opts(), in case it can not be determined automatically. @@ -316,7 +318,12 @@ SPEC SETUP *lazy.nvim-🔌-plugin-spec-spec-setup* build fun(LazyPlugin) or string or build is executed when a plugin is installed or updated. false or a list of build See Building for more information. commands - --------------------------------------------------------------------------------------------------- + -------------------------------------------------------------------------------------------------- +Always use `opts` instead of `config` when possible. `config` is almost never +needed. + + + SPEC LAZY LOADING *lazy.nvim-🔌-plugin-spec-spec-lazy-loading* @@ -1241,6 +1248,8 @@ BEST PRACTICES *lazy.nvim-🔥-developers-best-practices* >lua { "nvim-lua/plenary.nvim", lazy = true } < +- Always use `opts` instead of `config` when possible. `config` is almost never + needed. - Only use `dependencies` if a plugin needs the dep to be installed **AND** loaded. Lua plugins/libraries are automatically loaded when they are `require()`d, so they don’t need to be in `dependencies`.