Fix doc tag associations, warn about useless tags

[taminomara]

This commit fixes doc tag association for tags that appear after @class and other decls. It affects @see, @return_cast, @source, @version, @deprecated, visibility tags and custom (other) tags.

It also adds diagnostics for doc tags that couldn't be attached to any object, and therefore are ignored.

Fix #575.

[taminomara]

Note: this is the main change, the rest is just error reporting.

[badosu]

Thank you so much!

[lewis6991]

In Neovim we use other custom tags (e.g. @nodoc) for documentation generation.

We disable unknown-doc-tag to prevent warnings, but with this change we also now need to disable annotation-usage-error.

I think annotation-usage-error should only apply to annotations supported by emmylua.

[clason]

Sorry to do that again, but this PR introduced a regression (on nvim-treesitter, main branch):

--- nvim-treesitter/parsers.lua [1 error]
error: `@type nvim-ts.parsers` can't be used here [annotation-usage-error]
  -->: nvim-treesitter/parsers.lua:1:5

  1 │ ---@type nvim-ts.parsers
  2 │ return {

nvim-ts.parsers is defined as

---@alias nvim-ts.parsers table<string,ParserInfo>

[taminomara]

Sorry to do that again, but this PR introduced a regression (on nvim-treesitter, main branch):

This is not a regression, @type has no effect when attached to a return statement.

[taminomara]

I think annotation-usage-error should only apply to annotations supported by emmylua.

This warning happens when a tag has no effect, i.e. it's not attached to anything. Unless you roll a custom source parser, there's really no point in disabling these warnings. Can you elaborate on how you use custom tags?

[clason]

This is not a regression, @type has no effect when attached to a return statement.

The regression is that it now does: it throws an error where it didn't before (and doesn't anymore now).

[clason]

This warning happens when a tag has no effect

Then it should be a hint (like unused variable or unnecessary assert), not a hard error!

[taminomara]

Maybe we should demote annotation-usage-error to a warning then? Can you start make a separate issue?

Meanwhile, you can set a custom level for annotation-usage-error in .emmylua.rc:

{
  "diagnostics": {
    "severity": {
      "annotation-usage-error": "warning"
    }
  }
}

For context, right now, there's only one additional case when we emit annotation-usage-error: if you use @field before @class.

[clason]

(My issue is already fixed, so I'm not going to open an issue about it.)

[taminomara]

We disable unknown-doc-tag to prevent warnings, but with this change we also now need to disable annotation-usage-error.

BTW you can add custom tags into .emmylua.rc instead:

{
  "doc": {
    "knownTags": ["foo", ...]
  }
}

[lewis6991]

Unless you roll a custom source parser,

We have a custom parser, rolled with lpeg.

We currently use the tags @nodoc, @inlinedoc and @brief to aid with docgen.

[lewis6991]

This is not a regression, @type has no effect when attached to a return statement.

We use this to coerce the type of the expression in the return statement. Afaik this works in LuaLS.

It should be semantically equivalent to.

--- @type TYPE
local ret = EXPR

return ret

[xuhuanzy]

This is not a regression, @type has no effect when attached to a return statement.

The behavior is incorrect; ---@type should be allowed to be attached to a return statement.

[taminomara]

The behavior is incorrect; ---@type should be allowed to be attached to a return statement.

As of right now, it doesn't have any effect.