Clarify where lua setup code goes for lazy-loaded plugins

[anicolao]

⚠️ Please verify that this bug has NOT been reported before.

• [x] I checked all existing issues and didn't find a similar issue

Description

I am still thoroughly confused by the documentation on setting up plugins it seem. This snippet:

    extraPlugins = with pkgs.vimPlugins; {
      "statuscol.nvim" = {
        package = statuscol-nvim;
        setup = ''
          require("statuscol").setup({
            segments = {
              { sign = { namespace = { "gitsigns" }, maxwidth = 1, auto = false }, },
              { sign = { namespace = { "diagnostic/signs" }, maxwidth = 1, auto = false }, },
              { text = { require("statuscol.builtin").lnumfunc } },
              { sign = { name = { "coverage.*" }, maxwidth = 1, colwidth = 1, auto = false, fillchar = "╏" }, },
              { sign = { name = { ".*" }, maxwidth = 1, colwidth = 1, auto = false, wrap = true }, },
            },
          })
        '';
      };
    };

works fine to configure statuscol.nvim, but the same contents inside lazy.plugins = with pkgs.vimPlugins; { does not work.

The documentation doesn't contain an example to show how to call setup for lazy loaded plugins, and I couldn't find a way to do it.

👟 Reproduction steps

Write:

    lazy.plugins = with pkgs.vimPlugins; {
      "statuscol.nvim" = {
        package = statuscol-nvim;
        setup = ''
          require("statuscol").setup({
            segments = {
              { sign = { namespace = { "gitsigns" }, maxwidth = 1, auto = false }, },
              { sign = { namespace = { "diagnostic/signs" }, maxwidth = 1, auto = false }, },
              { text = { require("statuscol.builtin").lnumfunc } },
              { sign = { name = { "coverage.*" }, maxwidth = 1, colwidth = 1, auto = false, fillchar = "╏" }, },
              { sign = { name = { ".*" }, maxwidth = 1, colwidth = 1, auto = false, wrap = true }, },
            },
          })
        '';
      };
    };

as the lazy configuration.

👀 Expected behavior

The custom lua code should be called to load the plugin, either up front or upon encountering whatever trigger causes it to load.

😓 Actual Behavior

There is no attribute setup in the lazy branch resulting in an "option does not exist" error.

💻 Metadata

• system: "aarch64-darwin" - host os: Darwin 24.3.0, macOS 15.3.1 - multi-user?: yes - sandbox: no - version: nix-env (Nix) 2.24.12 - nixpkgs: /nix/store/crrwsv142k1vkwdba7q26y73760n4bll-source

📝 Relevant log output

error: The option `programs.nvf.settings.vim.lazy.plugins."statuscol.nvim".setup' does not exist. Definition values:

[NotAShelf]

CC @horriblename

[horriblename]

lazy.plugins.(name).after is the equivalent of extraPlugin's setup

extraPlugins came before lazy.plugins, and lz.n's semantics of before/after doesn't make sense for extraPlugins since those are always loaded on startup and you can't specify code to run before startup, hence the different name

I should add a note on this in the docs

[anicolao]

I saw after in the documentation in the example like this:

after = ''
        -- custom lua code to run after plugin is loaded
        print('aerial loaded')
      '';

and assumed that since a "setup" call wasn't shown, it had already been called (since it is "after the plugin is loaded"). Simply modifying the example to call setup would clarify. Using after does work in my configuration, so sorry I didn't just try it.

[horriblename]

ah, I forgot, setupModule and setupOpts exist for lazy.plugins, that is the preferred way to run setup. After is for custom lua code