refactor(test): add type annotations for the child object

[stasjok]

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md

Hey, I'm a big fan of type annotations, since they are helping writing code. It's far from perfect in lua, but it's still helpful. Working with child object is a very frequent task and I always wanted completions for child.api for example. I did a first step to that goal in my fork and quiet happy with the results. I thought that it can be useful for someone else too. But since that PR #437 (comment) I remembered that this is not really that important for you. If you decide to close this, that's OK. I think I can use a fork with type annotations added (and I can even add expectations and new methods there instead of helpers in each project).

I want to improve type annotations for some other public functions too, like new_set() that is often used when writing tests (I have a trouble remembering that pre_case is not a top level attribute, but a sub-attribute of hooks).

In helpers it's expected to use something like:

-- Monkey-patch `MiniTest.new_child_neovim` with helpful wrappers
Helpers.new_child_neovim = function()
  ---@class helpers.child: MiniTest.child
  local child = MiniTest.new_child_neovim()
...

This way helpers.child will have all original and added methods annotated. But for lua-language-server actually recognize it, helpers need to be required, not dofiled.

-- Won't work
local helpers = dofile('tests/helpers.lua')
-- Works
local helper = require('tests.helpers')

Also it can be used like this:

local helpers = dofile('tests/helpers.lua')
---@type helpers.child
local child = helpers.new_child_neovim()

The only issue is with mini.doc. It doesn't recognize @return tag correctly. @return tag can be:

• <type>
• <type> #<comment>
• <type> <var name>
• <type> <var name> <comment>

So it would be helpful for mini.doc to support custom types (not only standard). So that doc text matches what is a type, and what is a comment.

[echasnovski]

Thanks for the PR!

Currently I indeed find "type annotations everywhere" approach usually more cumbersome than not using them at all. Especially as it requires a lot of boilerplate with not enough pay-off in my opinion. And even more especially if it requires a "trick to fool lua-language-server into assigning vim types to the child methods".

That said, I've updated documentation to at least reuse what is already there and have LSP completion for child methods (without verbose documentation though).

I want to improve type annotations for some other public functions too, like new_set() that is often used when writing tests (I have a trouble remembering that pre_case is not a top level attribute, but a sub-attribute of hooks).

Thanks, but that'll be not necessary.

The only issue is with mini.doc. It doesn't recognize @return tag correctly. @return tag can be:

'mini.doc' doesn't comply with LuaCATS (yet). See #666.