docs(icons): update `get` documentation to document all return values

[mehalter]

• [x] I have read CONTRIBUTING.md
• [x] I have read CODE_OF_CONDUCT.md

The documentation strings should follow the LuaCATS standard for the most part which documents multiple returns with multiple @return comments.

Relevant links:

• Documentation for @return, only one that shows multiple return values is the example for variable arguemnt returns: https://luals.github.io/wiki/annotations/#return
• Example code in the LuaCATS organization in the luv repo of a function with multiple returns: https://github.com/LuaCATS/luv/blob/main/library/uv_signal_t.lua#L54-L61

Currently this results in documentation generated with multiple Return headers. I believe this is intended since this is a case explicitly tested in the mini.doc test suite. If we want to move this to behave more like Parameters that could also be nice and more clear to the user. I have this change working in a separate branch. I could add that to this PR if desired or follow up with a separate PR. There would also need to be some amount of discussion or thought of whether or not to stick with the word "Return" for the section header here or move to "Returns" since similarly to "Parameters" and "Fields", there can be many.

I know that these documentation strings are more meant to align with mini.doc rather than the standard LuaCATS right now and it may be a goal to move to supporting the standard in the future (#666). So the strings here still aren't "true" LuaCATS since they don't have names for the returns or the # indicating it's a labelled return. So let me know if this is just out of scope for the time being and will be implemented correctly later when the open issue about LuaCATS is resolved.

Let me know what you think and I can update my PR as necessary to align with the project's goals. Glad to help in any way I can 😄

[echasnovski]

Thanks for the PR!

I know that these documentation strings are more meant to align with mini.doc rather than the standard LuaCATS right now and it may be a goal to move to supporting the standard in the future (#666). So the strings here still aren't "true" LuaCATS since they don't have names for the returns or the # indicating it's a labelled return. So let me know if this is just out of scope for the time being and will be implemented correctly later when the open issue about LuaCATS is resolved.

Yes, I am afraid this is out of scope for the time being. I hope to eventually get back to this during #666. Nevertheless, information you linked in first comment will be useful. Thanks!

Closing as "planned but not now".

[mehalter]

Ok cool thanks! It's just a shame this is now the one function in mini.nvim that is not compatible with the Lua language server at all. I'll just disable diagnostics for this module in my code