Align the documentation of how to do debugging with official docs, help beginners to get started with debugging #3272
Comments
bjornregnell
changed the title
|
Example of misalignemnt: On the official docs it says to press the "Launch program" button but in Scala Metals it is "Run and Debug" but then it starts the "run config"-dance that is much more difficult to a beginner than just pressing "run | debug" above your @main. But that does not appear if you don't have a build.sbt, which is not obvious from the official debugging docs of vs code. |
|
If you follow the offical docs you risk ending up with |
|
Thanks @bjornregnell ! We should for sure update the docs to be more beginner friendly. I will take a look next week at that. |
|
I guess Metals need to automatically create a valid launch config in order for the official docs to work. If we cannot impact the official docs then we need to adapt so they work. Searching internet for "vs code debug" will land most beginners on the official docs... |
tgodzik
added
debug
|
Related scalameta/metals-vscode#767 <- however I don't think it will cause Metals to pop up on the main page, but should be more discoverable. |
|
How about providing a launch config out-of-the-box so the standard "Launch Program" button "just works"? Is this related to the label? Or what does it take to provide such a config to avoid the 'JSON with Comments' popup... |
I am thinking we could try and run the existing command that will try to discover a main method in the current file instead of creating the config with the pop ups, which I never really found too useful. We could also link to the official docs from the Metals page as it's much more complete when it comes to the debugging explanations, what do you think? |
|
Well, as long as the button that is given if you just click the Bug-tab on the left and the launch button just works then its fine (I thought that there perhaps had to exist a JSON launch config in order for the button to work, but if it's not needed then its fine) |
I think it should be possible to not need it, but I ahven't managed yet to figure it out microsoft/vscode#54212 |
|
Ok, so I did some research and I think currently the best approach would be to prefill the launch.json configuration for the user instead of making the users fill everything by themselves. This will require some discover endpoint on the Metals side, but it can be done on top of #3277 We can also use the dynamic configuration, which shows up when users run I am also thinking of adding another dynamic configuration option for running things in the current file, which could be resolved dynamically based on the current open file. It would be cool to have that instead available as the default F5 behaviour, but I think that's not possible and the best thing we can do is prefill the json (will need to confirm that still.) |
|
That sounds promising! 💟 |
Previously, when no launch.json was configured we would show a chain of quick picks so that the user would guided through configuring their entry. This however, would not be obvious to the users and would show up only once at the start. This was also not too obvious for the bginners and prompted scalameta/metals#3272 Now, we remove the config generation and replace it by mechanism to detect if no launch.json is available and then run the command to run anything in the current file. We might return partly to config generation when we have a mechanism to discover the the mains and tests, which can then be used to suggest new entries to launch.json.
Previously, when no launch.json was configured we would show a chain of quick picks so that the user would guided through configuring their entry. This however, would not be obvious to the users and would show up only once at the start. This was also not too obvious for the bginners and prompted scalameta/metals#3272 Now, we remove the config generation and replace it by mechanism to detect if no launch.json is available and then run the command to run anything in the current file. We might return partly to config generation when we have a mechanism to discover the the mains and tests, which can then be used to suggest new entries to launch.json.
Previously, when no launch.json was configured we would show a chain of quick picks so that the user would guided through configuring their entry. This however, would not be obvious to the users and would show up only once at the start. This was also not too obvious for the bginners and prompted scalameta/metals#3272 Now, we remove the config generation and replace it by mechanism to detect if no launch.json is available and then run the command to run anything in the current file. We might return partly to config generation when we have a mechanism to discover the the mains and tests, which can then be used to suggest new entries to launch.json.
|
This should now work properly when just clicking run in any file. Do let us know @bjornregnell if there is anything else you feel we can improve (aside from obvious Metals stability) |
|
Works like a charm! ❤️ |
I'm trying to help my beginner programming students to grok how to use the debugger in vs code and one problem is that this page https://code.visualstudio.com/docs/editor/debugging does not mention Scala and this page https://scalameta.org/metals/docs/editors/vscode/#running-and-debugging-your-code does not really show how to do debugging in vs code and it is not really aligned with the official doc on the debugger and how to set it up.
Expected behavior
Align the info and make it easier for a beginner programmer to get started with debugging with Metals. Would it even be possible for the official MS doc on vs code to point also to the Scala extension and for the Metals VS code page to align or link to the setup as in the official guide to reduce confusion?
The text was updated successfully, but these errors were encountered: