Is there a way to separate code and annotations in different files?

[lua-rocks]

In the hard times, when I did not have a computer (because of the war in my country), I wrote code on android tablet.
Since there is no IDE for android with emmylua support, each of my modules looked like this:

📂 my_module
├── 📜 init.lua
└── 📜 README.md

That is, I wrote the code in one file and its documentation in another. And I like this approach because the code stays clear of comments and I can easily generate documentation for the whole project using the mkdocs or mdbook utilities.

Now I have a laptop and have access to VSCode again, but I don't want to rewrite init.lua by adding emmylua annotations to them. I want to leave the code clean of all comments, so as not to lose that simplicity of working from primitive android editors.

Instead, I would like to add a third file to each of my modules, such as emmy.lua, in which I could document the code from init.lua in emmylua format. Can you please tell me if this is possible? Thank you.

[flrgh]

I'm also interested in something like this, for a slightly different reason:

I regularly edit .lua files in projects that don't use annotations (and the maintainers don't want them) or use a different annotation format, like LDoc.

I can create annotations for these things in a different tree outside of the workspace, but the problem is that the original source file is still read and parsed, which can create conflicts and duplicate type definitions. In short, I'd like to be able to tell the server:

1. The file /path/to/annotations/foo/bar.lua contains the definitive type annotations for module foo.bar
2. Do not parse or attempt to use any other type definitions for foo.bar, even when I edit {{workspace}}/foo/bar.lua or some other file in {{workspace}} that uses foo.bar.

Basically, a tie-breaker of sorts.

[C3pa]

Yes, both are possible. Let's address lua-rocks' question first.

Let's consider the following folder structure:
📂 my_module,
├── 📜 meta.lua
├── 📜 init.lua
└── 📜 README.md

And if the init.lua looks like this:

function doSomething(params)
	-- function body
end

You can annotate that like this inside meta.lua:

-- Let's mark this file as an annotation file:
---@meta

-- Now let's annotate our code:

--- This function does something...
---@param params table<string, number>
---@return string
function doSomething(params) end -- Note that we have a "mock" function declaration here

[C3pa]

The suggested approach has one drawback: the definitions defined in our meta.lua and the ones defined in init.lua will be shown in the autocomplete tooltip. (Now we are coming to the issue flrgh described).

I decided to work around this issue by disabling the scanning of the files that contain the function's implementation via settings, and loading my meta annotation file, also with settings. And then, in that case, flrgh, you can distribute the settings file with your annotations. The settings file works a bit differently in various editors. There is a guide on that on the Uncyclo. Am I understanding your use case correctly?

Here you can see an example of a project that uses a similar setup for VSCode.

[lua-rocks]

It doesn't work for me. The params type is still any and I don't see comments.

[C3pa]

Yes, unfortunately by using this method you don't get autocomplete inside init.lua file. But the described setup will give you proper autocomplete suggestions in other Lua modules using your my_module.

Also, in the image above we can see the duplicate type definitions in the autocomplete suggestion, as mentioned by @flrgh.