Don't send custom markup in Language server messages

[dwexel]

Describe the project you are working on

I'm working on a game; I'm using and developing a sublime text add-on in order to help make my game. Sublime text supports LSP and I've been able to use it with Godot's LSP server.

Describe the problem or limitation you are having in your project

Godot returns markdown formatted (with BBCode?) for documentation popups/tooltips/whatyoucallthem

for example;

{
    'contents': 
    {
        'kind': 'markdown', 
        'value': '\tfunc @GlobalScope.print(...) -> void\n\nConverts one or more arguments of any type to string in the best way possible and prints them to the console.\n\n`codeblocks`\n\n`gdscript`\n\nvar a = `1, 2, 3`\n\nprint("a", "b", a) # Prints ab`1, 2, 3`\n\n`/gdscript`\n\n`csharp`\n\nvar a = new Godot.Collections.Array { 1, 2, 3 };\n\nGD.Print("a", "b", a); // Prints ab`1, 2, 3`\n\n`/csharp`\n\n`/codeblocks`\n\n**Note:** Consider using `push_error` and `push_warning` to print error and warning messages instead of `print` or `print_rich`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.\n\n'}, 
        'range': 
        {
            'end': {'character': 4, 'line': 273}, 
            'start': {'character': 4, 'line': 273}
        }
}

which results in this misprint

Describe the feature / enhancement and how it helps to overcome the problem or limitation

The Godot language server implementation might be changed. if godot wants to use a custom format for docstrings that's fine, but it shouldn't be on individual (LSP) client implementations to adapt to that

Describe how your proposal will work, with code, pseudo-code, mock-ups, and/or diagrams

Godot could instead return messages with the standard code block markdown syntax

```gdscript\n<code>\n```

or something like it??

If this enhancement will not be used often, can it be worked around with a few lines of script?

it's already being worked around in the official pugin for vscode

Is there a reason why this should be core and not an add-on in the asset library?

Because other non-engine third parties will be building on top of this change, and it's a very small and straightforward chagen

[RedMser]

I needed a similar conversion as part of a plugin I was working on, so I fully agree. The LSP specs also specify GFM as their markdown syntax, so this is indeed the one that should be implemented here.

The issue is that there are multiple BBCode flavors in Godot:

1. BBCode as supported by RichTextLabel.
2. BBCode as used in the XML documentation, supported by the editor tooltip and documentation viewer.

So if we wanted to expose this to scripting, it might be expected that it supports flavor 1, but in reality we want to implement flavor 2 for our purposes here. Maybe for starters, it should be a private implementation for flavor 2, until there is actual demand to make such a feature available to scripts as well.

---

Needs some research to check how links that reference members, classes, enums etc. should be formatted, so that the VSCode extension for example could open the built-in documentation viewer, or jump to the corresponding implementation file.

[rwols]

For formatting links to a built-in documentation viewer: one way to handle this gracefully is to add a boolean option to the initializeOptions in the initialize request that informs the language server wether the client is able to handle in-editor documentation pages. If enabled, the language server can use a custom URI scheme. For languages that don’t support a built-in viewer, the language server can use plain https:// URI schemes that point to documentation available online.

Editor clients can then parse the URI and if it’s of the custom scheme type redirect to their in-editor viewer.

[RedMser]

I've investigated the BBCode flavors, and they're handled completely separately. One in RichTextLabel::append_text and one in EditorHelp::_add_text_to_rt. I even found yet another parser in mono's BindingsGenerator::bbcode_to_text.

I believe this proposal should not be solved by creating a fourth parser for this purpose, but instead refactor all of these into one BBCode parser class that returns a list of tokens (or as RichTextLabel calls them Items). This would then be used for all BBCode flavors, as long as it is configurable enough to make it work.

I opened #10339 with a proposal on a possible way to approach this.