What exactly can custom addons do and how can I write one?

[bavalpey]

I've read through the documentation/wiki regarding custom addons and am very confused.

The only information the wiki says is:

Plugins allow you to create a custom syntax that will then be output to a separate file.

But I don't understand what this means. The video on the page shows the "diffed.lua" file outputting valid lua code from the custom syntax on the right. What effect does this achieve? Are users of the plugin supposed to use the diffed.lua file as the final source?
Or is the diffed.lua file just what the LSP uses to analyze the code, treating that file as if it is the real lua it is analyzing.

A few other things: I can't figure out how to develop the custom add ons. Several examples start with using require 'plugins.astHelper' etc. But where are these lua files located? Do I need to mark an include path somewhere for the plugins from Lua LSP?

What exactly does onTransformAST do, and how is it different from onTextChanged? Does the changed ast also only get output to a separate file?

[Frityet]

But I don't understand what this means. The video on the page shows the "diffed.lua" file outputting valid lua code from the custom syntax on the right. What effect does this achieve? Are users of the plugin supposed to use the diffed.lua file as the final source?

The way its supposed to be used is that the plugins are only to make your code work in LuaLS, so for example

local i: integer = 4

is a valid teal programme, but is not standard lua syntax, therefore to make this work with LuaLS you would define a plugin that would replace the : integer with a ---@type integer on the line above, and the output to this is produced in the diffed.lua file, which is used instead of the file you are editing

Or is the diffed.lua file just what the LSP uses to analyze the code, treating that file as if it is the real lua it is analyzing.
this is correct

A few other things: I can't figure out how to develop the custom add ons. Several examples start with using require 'plugins.astHelper' etc. But where are these lua files located? Do I need to mark an include path somewhere for the plugins from Lua LSP?

plugins.astHelper is internal to LuaLS but can be used by any plugin (see here). You can find the scripts themselves in the source of this repo

What exactly does onTransformAST do, and how is it different from onTextChanged? Does the changed ast also only get output to a separate file?

the PR that introduced it. Just for editing the AST instead of using the text editing as before

[bavalpey]

How do I use plugins.astHelper and get the completion? Do I specify it as a path in my settings.json?

[bavalpey]

Well I figured this out.. But now I'm trying to figure out how to test my plugin.. I followed the steps but nothing seems to be logged when I follow them...