feat(API): add emmylua annotations

[kylo252]

I think it might be better to let the API documentation live inside the code, and it also benefits from LSP capabilities

---

TODO

• I've only added a few so far
• autocompletion seems busted, I have a feeling it's something to do with some internal cache invalidation

[L3MON4D3]

I agree, it makes sense to have the documentation next to the code, should prevent it becoming outdated.

It would be really cool to automatically generate the entries in DOC.md (because I'd like to keep those as well) from these annotations, do you know if there are ways to do that?

[kylo252]

I agree, it makes sense to have the documentation next to the code, should prevent it becoming outdated.

It would be really cool to automatically generate the entries in DOC.md (because I'd like to keep those as well) from these annotations, do you know if there are ways to do that?

I was looking earlier at ldoc which is able to generate html, and in theory markdown as well, but I could never get it to work with markdown. I think it's missing a template or something.

There's also this script from neovim-core, https://github.com/neovim/neovim/blob/8055f9857b8e384634d457533dfdb08618fc36f0/scripts/gen_vimdoc.py#L2

Lastly, I had an idea to leverage LSP for this, but it's a bit fiddley (redirect hover request output)

  local write_tmpfile = function(data)
    local tmpname = os.tmpname()
    local file = io.open(tmpname, "w")
    if type(data) == "table" then
      data = table.concat(data, "\n")
    end
    file:write(data)
    file:close()
    return tmpname
  end
  local util = require "vim.lsp.util"
  vim.lsp.handlers["textDocument/hover"] = function(_, result, ctx, config)
    config = config or {}
    config.focus_id = ctx.method
    if not (result and result.contents) then
      -- return { 'No information available' }
      return
    end
    local markdown_lines = util.convert_input_to_markdown_lines(result.contents)
    markdown_lines = util.trim_empty_lines(markdown_lines)
    if vim.tbl_isempty(markdown_lines) then
      -- return { 'No information available' }
      return
    end
    local tmpfile = write_tmpfile(markdown_lines) -- can also just copy the lines into some register instead
    print(tmpfile)
    vim.cmd([[edit ]] .. tmpfile)
    return tmpfile
  end

[L3MON4D3]

LDoc looks promising, but I'm surprised that there is no tool that straightforwardly generates markdown
The LSP approach is interesting, is there a way to automate it?

[kylo252]

is there a way to automate it?

Here's my script so far, just give it a valid bufnr (check :LspInfo)
https://gist.github.com/kylo252/7b3edb23b55197316a33916fd79d942f

Here are the results, which as you can see need better formatting, but that's why I included the raw response as well
https://gist.github.com/kylo252/1dcc3f9da60e42786d7088caa8441f67

I'm also counting on the fact that you have more experience with string manipulation 😃

[L3MON4D3]

Oh wow, that looks pretty good already 👍👍
I won't be able to really get into helping you with it for some time though :/

[saadparwaiz1]

There's also this treesitter module available for generating documentation thorough Emmy

[L3MON4D3]

Interesting, but it only generates vimdoc (afaict) :/

[saadparwaiz1]

seems like this does the job? spinx generates rst by default but that works on github. if markdown is required this extension can be used?

[hinell]

Wonder why this one wasn't merged. Nice PR. Many projects are underdocumented.

[L3MON4D3]

Hey @kylo252, are you fine with merging this as-is (or, more-or-less as-is, after looking into how up to date it still is)?