`--doc` CLI argument does not work

[rhys-vdw]

How are you using the lua-language-server?

Command Line

Which OS are you using?

Windows WSL

What is the issue affecting?

Other

Expected Behaviour

Document generation, as documented here:

https://luals.github.io/wiki/usage/#--doc

Actual Behaviour

rhys@RhysDesktop:~/example-lua$ ~/lua-language-server/bin/lua-language-server --doc ~/example-lua/
root uri = file:///home/rhys/example-lua/
script/cli/doc/export.lua:304: attempt to concatenate a nil value (local 'outputDir')
stack traceback:
        script/cli/doc/export.lua:304: in field 'serializeAndExport'
        script/cli/doc/init.lua:235: in upvalue 'callback'
        script/lclient.lua:129: in function <script/lclient.lua:128>
stack traceback:
        script/lclient.lua:123: in function 'await.errorHandle'
        script/await.lua:35: in function 'await.checkResult'
        (...tail calls...)
        [C]: in function 'xpcall'
        script/timer.lua:52: in upvalue 'mWakeup'
        script/timer.lua:93: in upvalue 'onTick'
        script/timer.lua:236: in function 'timer.update'
        script/lclient.lua:139: in method 'start'
        script/cli/doc/init.lua:201: in function 'cli.doc.runCLI'
        script/cli/init.lua:22: in main chunk
        [C]: in function 'require'
        /home/rhys/lua-language-server/main.lua:78: in main chunk
        (bootstrap.lua):85: in main chunk
        [C]: in ?
script/lclient.lua:124: [19:48:24.474][error][#0:script/lclient.lua:123]: script/cli/doc/export.lua:304: attempt to concatenate a nil value (local 'outputDir')
stack traceback:
        script/cli/doc/export.lua:304: in field 'serializeAndExport'
        script/cli/doc/init.lua:235: in upvalue 'callback'
        script/lclient.lua:129: in function <script/lclient.lua:128>
stack traceback:
        script/lclient.lua:123: in function 'await.errorHandle'
        script/await.lua:35: in function 'await.checkResult'
        (...tail calls...)
        [C]: in function 'xpcall'
        script/timer.lua:52: in upvalue 'mWakeup'
        script/timer.lua:93: in upvalue 'onTick'
        script/timer.lua:236: in function 'timer.update'
        script/lclient.lua:139: in method 'start'
        script/cli/doc/init.lua:201: in function 'cli.doc.runCLI'
        script/cli/init.lua:22: in main chunk
        [C]: in function 'require'
        /home/rhys/lua-language-server/main.lua:78: in main chunk
        (bootstrap.lua):85: in main chunk
        [C]: in ?

stack traceback:
        [C]: in function 'error'
        script/lclient.lua:124: in function 'await.errorHandle'
        script/await.lua:35: in function 'await.checkResult'
        (...tail calls...)
        [C]: in function 'xpcall'
        script/timer.lua:52: in upvalue 'mWakeup'
        script/timer.lua:93: in upvalue 'onTick'
        script/timer.lua:236: in function 'timer.update'
        script/lclient.lua:139: in method 'start'
        script/cli/doc/init.lua:201: in function 'cli.doc.runCLI'
        script/cli/init.lua:22: in main chunk
        [C]: in function 'require'
        /home/rhys/lua-language-server/main.lua:78: in main chunk
        (bootstrap.lua):85: in main chunk
        [C]: in ?
/home/rhys/lua-language-server/bin/lua-language-server: script/lclient.lua:149: two hours later ...
====== C -> S ======
====== S -> C ======
====================
stack traceback:
        [C]: in function 'error'
        script/lclient.lua:149: in method 'start'
        script/cli/doc/init.lua:201: in function 'cli.doc.runCLI'
        script/cli/init.lua:22: in main chunk
        [C]: in function 'require'
        /home/rhys/lua-language-server/main.lua:78: in main chunk
        (bootstrap.lua):85: in main chunk
        [C]: in ?

Reproduction steps

1. Create a new folder
2. Add any documented lua file, I used this:

---@param x number
function foo(x) end

3. Run lua-language-server --doc <path-to-folder>

Additional Notes

I tried this on both Windows and WSL with the same result.

Log File

No response

[rhys-vdw]

I have discovered that this error goes away if I provide --doc_out_path! 🤦

I feel like the wiki would greatly benefit from an example!

[carsakiller]

I believe this is supposed to output to the log path if no --doc_out_path is provided.

[rhys-vdw]

I believe this is supposed to output to the log path if no --doc_out_path is provided.

Yeah, it's hard to decypher. But it fails with the same error on both windows and WSL for me.

On WSL I built from master, on Windows I downloaded latest release exe.

[tomlau10]

I remembered there was a heavy refactor on the doc generation code, don't know if it has broken anything 🤔
related PR: #2821, the outputDir variable seems to be introduced in it

[rhys-vdw]

This would benefit greatly from a default output dir, or an error log that catches that the param was not added and logs an error and example use.

[Mc-GrowlR]

I mentioned this issue in my previous issue, and I need to provide two options：
#2927
The reason for this error is because the directory address of the --doc_out_path option is not provided in the options. However, depending on the wiki, when the option is empty, it will be exported to the log folder by default, but I don't see my exported documents in the log folder. According to the error prompt, I finally found that the outputDir variable is nil. This is inconsistent with what the documentation says is the default address of the log directory.
In addition, due to this reason, the document export function of the luals plugin of vscode is disabled, and the error message displayed in the log file is shown in this issue. Because the value of the '--doc_out_path' option is missing, the 'outputDir' variable is nil.

[rhys-vdw]

I'm surprised that this file isn't using the type annotations that lua language server provides to alert the developer that the CLI arguments might be nil and force them to handle it. This all seems possible!

[Mc-GrowlR]

I'm surprised that this file isn't using the type annotations that lua language server provides to alert the developer that the CLI arguments might be nil and force them to handle it. This all seems possible!我很惊讶这个文件没有使用 lua 语言服务器提供的类型注释来提醒开发人员 CLI 参数可能为 nil 并强制他们处理它。这一切似乎都是可能的！

I looked at the source code of this file, and the error point was that the outputDir variable was concatenated with the string when the nil value was valued. I don't know when the default log folder path described in the documentation was given this parameter, perhaps the developers have their own considerations.
Also, not only that, there are also a lot of type conversion functions in the doc export function that are not commented, but I saw the doc.lua file when I first read this project, so I had a hard time reading it, and I wanted to serialize the output content, and I ended up with a burst stack.
Once again, my path to understanding has stopped.

[Luke100000]

I can confirm the output path fix, but for me the documentation includes the entire standard library (math, string, debug, _G, ...). Did I miss something?

[rhys-vdw]

@Luke100000 I have the same problem and a fix, but this seems like a different issue? I can't pull the workaround up now, but essentially it is providing a different config that sets all the default libraries to false. Let me know when you've opened an issue and I'll find a time to add the full workaround etc.

[Mc-GrowlR]

I can confirm the output path fix, but for me the documentation includes the entire standard library (math, string, debug, _G, ...). Did I miss something?

I've encountered this problem, I can just add some filters to a function in the doc.lua file.

[tomlau10]

the documentation includes the entire standard library (math, string, debug, _G, ...)

I think this is reported in another issue here: #2977