Wiki rework

[carsakiller]

Hello 👋

I am currently reworking the wiki to be neater and more detailed. I am starting this thread because I have some questions about the language server that I'll need some help finding answers for.

For my first (of many, I'm sure 😆) questions:

What effect does completion.showParams have? I have tried toggling it and completing functions and params and I don't see any effect.

[carsakiller]

Some diagnostics I have never seen and not been able to trigger but would like to in order to write descriptions for them:

• await-in-sync
• close-non-object
• codestyle-check
• count-down-loop
• duplicate-set-field
• newfield-call
• newline-call
• no-unknown
• spell-check
• undefined-doc-class
• undefined-doc-name
• undefined-doc-param
• undefined-env-child
• unknown-diag-code
• unreachable-code (I can only get action-after-return or code-after-break)

Some sample code that would trigger each one and/or a description would be great!

EDIT: All diagnostics have been documented 🎉. Just the syntax errors now but those are of lower priority.

[carsakiller]

There also appear to be some undocumented diagnostics. These are missing from doc/en-us/config.md:

• unknown-symbol

  local a = &

• malformed-number

  local num = 0.4.0

  I am currently adding them to the new wiki.

[carsakiller]

There are many more that can apparently be disabled with Lua.diagnostics.disable like err-assign-as-eq, err-comment-prefix but cannot be modified with Lua.diagnostics.Severity. This may be intended as these are errors and probably always should be, it just makes the documentation a bit harder as some diagnostics can have their severity changed and some cannot.

[Nexela]

for i = 10, 1 do end

local a ---@type something

print("somefakeworks")

  print(blah)

---@param aa string
---@param aa string
local function test(aa, bb) end

---@class Read: fake

local function test2()
  if true then
    return
  else
    return
  end
  print "test"
end
test2()


---@diagnostic disable: notacode

[carsakiller]

Of course, the only syntax I didn't test for count-down-loop 😆

It seems pretty hit-or-miss though 😕

-- warns
for i=10, 1 do end

-- does not warn
for i=100, 10, 1 do end

-- does not warn
for i=1, -10 do end

--does not warn
for i=-10, 10, -1 do end

[carsakiller]

I have never received any spell-check diagnostic. I tried the exact example you provided and still don't get one 🤔. I don't have any diagnostics disabled or anything. It is all default except "Lua.diagnostics.libraryFiles": "Enable"

[carsakiller]

Also not receiving any codestyle-check diagnostics.

[Nexela]

I would consider the count-down-loop one a bug in need of a reporting!

[carsakiller]

Reported!

[Nexela]

spell-check and codestyle-check are "none" by default

    "Lua.diagnostics.neededFileStatus": {
      "spell-check": "Opened!",
      "codestyle-check": "Opened!",
    },

Edit: They also might be set to "hint" by default too I can't remember that will only show up as three tiny dots and not show up in problems view

[carsakiller]

I found some info that will need to be made clearer in the wiki 😄

[Nexela]

"Lua.diagnostics.libraryFiles": "Enable"
Only affects files loaded via workspace.library and only applies the same severity settings

[Nexela]

local a = coroutine.create(function()
  coroutine.yield()
end)

[carsakiller]

Another diagnostic that is off by default. I looked through the defaults and seem to have found all of the ones that were off and turned them on now. Now I am just missing the truly rare ones 😉

[Nexela]

Probably off too

local A
---@type iolib
_ENV = {}
print(A)

[Nexela]

local d = {
  done
  ("this")
}

They are getting harder to come by!

[carsakiller]

This really has me wondering, why is there 3 different ways to disable diagnostics? There is Lua.diagnostics.disable, Lua.diagnostics.groupFileStatus, and Lua.diagnostics.neededFileStatus. This can get very confusing very quickly.

I think going with just neededFileStatus would make the most sense.

[Nexela]

lua.diagnostic.disable Because, well you might want to turn off diagnostics but use the rest

But I agree on the other two, I think groupFileStatus was added because there are a lot of diagnostics to be enabled/disabled same for groupSeverity

[carsakiller]

But Lua.diagnostics.disable isn't a boolean, it is a string[] where you specify each and every diagnostic you want to turn off. The only advantage is that it is more obvious that it turns off that diagnostic, no matter if the file is open, in the workspace, written backwards, or non-existent.

I think the best solution is to only use neededFileStatus and then offer some "presets" on the wiki or the discussions that can do a lot of the changes for you. That way you don't have to actually go through and change every setting for every diagnostic but also don't need groups.

[Nexela]

Must be getting late, I kept writing this in the wrong ones! oh well discussions all over the place for the win.

Lua.diagnostics.disable isn't a boolean
Well in that case then I agree 100% drop the other ones and just use needed!

[carsakiller]

Created an issue for it

[sumneko]

close-non-object

[sumneko]

duplicate-set-field

[sumneko]

newline-call

[sumneko]

The rest are syntax errors rather than diagnostics.

[carsakiller]

That explains why some of the warnings cannot be changed with Lua.diagnostics.neededFileStatus I guess. Why do they appear under Lua.diagnostics.disable but not under Lua.diagnostics.neededFileStatus? It makes sense to not be able to disable syntax error warnings, but they can be?

[Nexela]

See #1254

[carsakiller]

Well, I agree with Sumneko that you shouldn't be able to disable syntax errors because it could lead to deeply-nested issues that could be very difficult to diagnose... but it looks like you can disable them?

[sumneko]

Although it is not recommended, I allow you to disable specific syntax errors.

[carsakiller]

cast-type-mismatch is listed under the luadoc and type-check groups - which, through testing, seems correct. I feel like this shouldn't be the case though as all other diagnostics belong to only one group and it seems like more of a type-check error rather than a luadoc error.

[carsakiller]

Also according to the linked resource, the following diagnostics do not have a group:

• action-after-return
• args-after-dots
• block-after-else
• break-outside

[carsakiller]

The groups add an unnecessary complexity, which is another reason why I think there are too many ways to toggle diagnostics and they should just be removed.

[sumneko]

Also according to the linked resource, the following diagnostics do not have a group:

• action-after-return
• args-after-dots
• block-after-else
• break-outside

They are syntax errors.

[carsakiller]

For ---@cast, what is the difference between:

---@type integer
local x

---@cast x +?

and

---@type integer
local x

---@cast x +nil

Do they not both imply that x may be nil/unknown?

[sumneko]

? and nil is almost same.
I originally wanted ? to represent the falsy value(nil|false), but later I found that there will be a lot of problems, so now I can only represent nil now.

[carsakiller]

Maybe to avoid confusion I will only document nil and not ? for now until it gains some different functionality.

[carsakiller]

Currently documenting @generic but while testing it, it seems to be behaving weirdly when being used in a class. As I am unsure if this is user error or a bug, I thought I'd ask here first before creating an issue.

---@class Array<T>: { [integer]: T }

---@type Array<string>
local arr = {}

-- correctly warns that I am assigning a boolean to a string
arr[1] = false

-- no warning despite indexing with a string instead of an integer
arr["foo"] = "bar"

-- correctly does not warn as I am following the type correctly
arr[3] = "Correct"

Behaves even weirder for a dictionary:

---@class Dictionary<T>: { [string]: T }

---@type Dictionary<boolean>
local dict = {}

-- no warning despite indexing with a number
dict[1] = "incorrect"

-- no warning despite assigning a string
dict["foo"] = "bar?"

-- correctly does not warn as I am following the type correctly
dict["correct"] = true

[sumneko]

This should be some issues.

[carsakiller]

Created #1378

[carsakiller]

One other thing, when is @generic actually necessary? As you can see in the examples above, I don't actually use @generic, instead I use <T>.

Do I only use @generic when annotating a function? Or maybe only when there are two of them?

---@generic A
---@generic B
---@param a A
---@param b B
---@return A, B
function test(a, b) end

[carsakiller]

I am nearing the end of the rework of the wiki and there are a few things that I would like to discuss, @sumneko.

I have seen many commits to the wiki where a file is created with no content by mistake (I assume while following dead links). This is cluttering the commit history and serves as a concerning reminder that someone malicious could temporarily delete parts of the wiki.

Can we change the permissions of the wiki so that not everyone has access to change it? I spent a lot of time trying to cover everything so there should not be a need for large changes from the community anymore. According to GitHub's docs the wiki can restrict write access to "collaborators" only.

So to commit my changes, I would need to be made a "collaborator". This would require a serious amount of trust due to the permissions that grants so if you are not comfortable with that, I understand. However, if I were made a collaborator, I would also be able to take on a larger role regarding documentation. I have not yet dived into adding to the language server code-wise but I am definitely able to help with improving/correcting documentation/translations. I would be able to help add documentation in the future and handle any issues concerning documentation, if that interests you.

Alternatively, you could create a repo dedicated to the wiki where trusted people could be added as collaborators with no worries of someone messing with the language server itself. Issues regarding documentation would then have to be split between the two repos though. Due to the wiki being a git repository that doesn't really have any of GitHub's features, you or another collaborator on this repo would then have to manually commit changes from the other repository.

[sumneko]

I am considering whether to change the Wiki to a document file (store in the doc directory) so that the community can submit documents and review through PR.

[Nexela]

Storing the wiki as a branch to the repo would be easy to manage and support PR's, could additionally be a submodule.

[carsakiller]

Making it it's own directory or orphan branch would be a nice way to limit the wiki to PRs and collaborators only, but it does mean we won't have the sidebar for navigating.

That feature is super useful as most, if not all markdown readers have them - except for, yup, markdown files in a directory. They instead get this button that drops down to a tiny scrolling container of headings, it isn't very useful.

I feel pretty confident in saying most people don't know that button even does what it does and it makes navigating a terrible experience.

Another alternative would be to use GitHub pages to host our own wiki that way we can limit writing to PRs and have a sidebar or whatever other styling/customizations we want. The downside is that it is more work to set up.

[sumneko]

The advantage of placing in the project is that it can be released with the project, but navigation is indeed a trouble.

[carsakiller]

That is true, it also increases the project size, which may or may not be too important, depending on how many people would:

A: Be able to find it if they installed through VS Code
B: Find local documentation useful
C: Prefer to just follow a link to a webpage with the documentation

I could definitely see it being useful to include in the source code if we could link to it like how the Lua docs are linked to (using virtual documents?):

This would be great for using with the VS Code Extension, but we would still need a wiki available elsewhere I feel.

[carsakiller]

My rework of the wiki is complete! How are we thinking I go about submitting these changes? Would you like to see the changes first or are you okay with me committing them all at once to the wiki? Are we going to include the wiki in the source code? A separate repository/branch? 😵‍💫

There are a lot of changes so most links to the wiki will probably be broken. I can help track them down and let you know what needs changing there too.

[carsakiller]

No problem!

The wiki is its own Git repository, so worst case if someone does do something malicious to a page, it can always be reversed. I just thought if mostly everything has been covered now, there shouldn't be a need for many people to contribute lots of changes, it should just be minor fixes or small additions when a new feature is added. I am all for including the community, whether you want to close public edits and do issues, or a separate branch and do PRs, or a separate repo, or a submodule.... I think they all have their own pros and cons. Whatever you would prefer, I am happy to help!

[sumneko]

I have invited you: https://github.com/sumneko/lua-language-server/invitations

[carsakiller]

Joined! So do you have a preferred method for documentation? Maybe one of the ways we discussed in the above thread?

[sumneko]

I have no idea, maybe store them in this project and copy the contents to wiki?

[carsakiller]

Wiki is live on this repo now! I will be opening a PR to edit the links in the README.