Hover documentation is truncated for some symbols

[hauserx]

See most prominent example here:

Looks like vscode is accepting some tags, but for uknown it simply removes content.

Possible solution 1: change vscode bazel extension

Applying this patch to vscode-bazel seems to do the trick:

--- a/src/extension/extension.ts
+++ b/src/extension/extension.ts
@@ -159,6 +159,7 @@ function createLsp(config: vscode.WorkspaceConfiguration) {

   const clientOptions: LanguageClientOptions = {
     documentSelector: [{ scheme: "file", language: "starlark" }],
+    markdown: { supportHtml: true },
   };

Possible solution 2: Sanitize documentation

Remove html tags or/and replace those with marksdown
Possible crate to use, seems pretty lightweight: https://github.com/letmutex/htmd

Additional example: nvim

Example does not seem pretty in nvim as well (at least with my config). Not sure whether can teach nvim to understand html, possibly then option 2 would be better.

[hauserx]

Couple of points noted when creating a solution for the immediate issue:

• It would be really nice if bazel exposed the built in symbols with documentation through bazel info, building it using gendoc in bazel source seems sub-optimal
• The current documentation harvested by gen_api_proto is tuned to create https://bazel.build/rules/lib/overview :
  • docs contain links to relative pages,
  • some texts makes sense when generated but less so when presented through LSP
  • there is another set of pages with description of the same symbols: e,g, https://bazel.build/reference/be/functions
  • some types in exported protos are human readable and not machine readable, like: type: "<a class=\"anchor\" href=\"../core/list.html\">sequence</a> of <a class=\"anchor\" href=\"../builtins/Subrule.html\">Subrule</a>s"
• The gen_api_proto does not expose information about WORKSPACE, MODULE and other symbols, but with small tweaks it can be changed to do. I will try to send a PR to bazel (Bazel exports methods for other types, but those are not used by ApiExporter through libraries it calls).
  • After adding those symbols the logic that replaces missing global symbols could be simplified
  • Found PR that aims to export module level builtins: Include Bzlmod globals in builtin.proto bazelbuild/bazel#21929
• Maybe buildin binary file could be replaced with text file (like pbtxt or json), just to avoid having binary files in the repo.
• builtins.bin contain types and functions with the same names. Right now documentation from functions is presented in LSP, but types have better documentation (e.g. DefaultInfo function has The DefaultInfo constructor while the DefaultInfo type has much more extensive documentation)