Document r/rmd.lua and introduce `is_in_code_chunk(language, verbose)`

[jalvesaq]

What language server or linter do you use for Lua?

If I write this:

---@param s string
local do_something = function (s)
    print("The argument is " .. s)
end

do_something({"an argument"})

The LSP complains that "Cannot assign table to parameter string. - table cannot match string - Type table cannot match string". However, if I put only two dashes and a space before the @, there is no diagnostic message, and the comments are highlighted as normal comments:

-- @param s string
local do_something = function (s)
    print("The argument is " .. s)
end

do_something({"an argument"})

I'm using lua_ls as language server + 'folke/neodev.nvim' + 'ray-x/lsp_signature.nvim'. So far, I don't know how to integrate selene as linter.

[jalvesaq]

I discovered how to integrate selene:

    {
        'nvimtools/none-ls.nvim',
        config = function ()
            local null_ls = require("null-ls")
            null_ls.setup({
                sources = {
                    null_ls.builtins.diagnostics.selene,
                },
            })
        end
    },

[PMassicotte]

Interesting, I am not using null-ls, I will try to figure it out.

[jalvesaq]

@she3o I'm reviewing your pull request. Sometimes, you explain in English what is already written in Lua. We have to describe briefly what the function does in the annotation right above the function because those who are writing code calling the function are not looking at the function's code. But those people inspecting the code of the function are supposed to know Lua, and, if unsure, they should read Neovim documentation to know what a Vim/Neovim function does. In many places, we have to add context explaining why the code does something. That is, add information that is not in the function itself.

The same advice is valid for academic papers. We should not repeat in the text what is in the tables and figures, unless our audience hasn't received academic training.

[she3o]

I also use lua_ls inside the lazy.vim distribution. The linter doesn't complain in my case. I'll look into why but I guess Mason or Lspconfig in Lazy.vim presets some configs?

The annotations above each function appear inside the function signature. Perhaps you meant the inline comments?

I add those the first time I inspect code. I feel that if they help me they may provide easy entry for any future contributers. As I understand the general module structure they indeed become less fruitful. The only exception I can think of is explaining vim.fn.* that might not be obvious if one didn't use Vimscript

[jalvesaq]

That said, you managed to merge two functions, and I couldn't note any new bugs in a quick test. I would like to get rid of the vim.b.IsInRCode variable but it makes the code cleaner at other places, where we would have to call a different function for each file type (r, rhelp, rmd, quarto) and syntax type (rdoc).

[jalvesaq]

You should get a diagnostic warning on this:

---@param s string
local do_something = function (s)
    print("The argument is " .. s)
end

do_something({"an argument"})