Improving doc comments syntax highlighting in hovering

[aspeddro]

After #97 and #525 have been merged we can provider basic syntax highlight when hovering.

Current state

Apparently vscode does not detect ```res example as rescript syntax. In markdown highlighting works.

Proposal

Convert ```res example to rescript. This can be done on the client side `client/src/extension.ts`, but I'm more +1 to do it in analysis bin as it wouldn't affect other clients.

As the return is markdown we could create sections using the word after ```res?

From:

```res example

To:

## Example\n```rescript

Example:

From:

Constructs a RegExp object (Js.Re.t) from a `string`.
Regex literals `%re("/.../")` should generally be preferred, but `fromString`
is useful when you need to dynamically construct a regex using strings,
exactly like when you do so in JavaScript.

```res example
let firstReScriptFileExtension = (filename, content) => {
  let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content)
  switch result {
  | Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1])
  | None => None
  }
}

// outputs "res"
firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js")
```

To:

Constructs a RegExp object (Js.Re.t) from a `string`.
Regex literals `%re("/.../")` should generally be preferred, but `fromString`
is useful when you need to dynamically construct a regex using strings,
exactly like when you do so in JavaScript.

## Example

```rescript
let firstReScriptFileExtension = (filename, content) => {
  let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content)
  switch result {
  | Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1])
  | None => None
  }
}

// outputs "res"
firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js")
```

Below an example after convert res to rescript. Note: indentation at the beginning of the line are preserved, we must remove them.

[cristianoc]

CC @zth @ryyppy

[ryyppy]

It doesn't detect "res" for syntax highlighting? what happens if it's called "rescript example"?

According to the markdown spec, the meta tags should not impact the language detection.

[ryyppy]

It doesn't detect "res" for syntax highlighting? what happens if it's called "rescript example"?

According to the markdown spec, the meta tags should not impact the language detection.

[aspeddro]

It doesn't detect "res" for syntax highlighting?

No.

What happens if it's called "rescript example"?

Doesn't work either

textDocument/hover response

{
  jsonrpc: '2.0',
  id: 52,
  result: {
    contents: '```rescript\n' +
      'string => Js.Re.t\n' +
      '```\n' +
      '\n' +
      '\n' +
      '  Constructs a RegExp object (Js.Re.t) from a `string`.\n' +
      '  Regex literals `%re("/.../")` should generally be preferred, but `fromString`\n' +
      '  is useful when you need to dynamically construct a regex using strings,\n' +
      '  exactly like when you do so in JavaScript.\n' +
      '\n' +
      '```rescript example\n' +
      '\n' +
      '  let firstReScriptFileExtension = (filename, content) => {\n' +
      '    let result = Js.Re.fromString(filename ++ "\\.(res|resi)")->Js.Re.exec_(content)\n' +
      '    switch result {\n' +
      '    | Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1])\n' +
      '    | None => None\n' +
      '    }\n' +
      '  }\n' +
      '\n' +
      '  // outputs "res"\n' +
      '  firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js")\n' +
      '  ```\n'
  }
}

Rust analyzer and ocaml lsp render with syntax highlights

rust_analyzer use ```rust

[Trace - 5:26:15 PM] Received response 'textDocument/hover - (14)' in 2ms.
Result: {
    "contents": {
        "kind": "markdown",
        "value": "\n```rust\nstd::macros\n```\n\n```rust\nmacro_rules! println\n```\n\n---\n\nPrints to the standard output, with a newline.\n\nOn all platforms, the newline is the LINE FEED character (`\\n`/`U+000A`) alone\n(no additional CARRIAGE RETURN (`\\r`/`U+000D`)).\n\nUse the [`format`](https://doc.rust-lang.org/nightly/alloc/macros/macro.format.html) syntax to write data to the standard output.\nSee [`std::fmt`] for more information.\n\nUse `println!` only for the primary output of your program. Use\n[`eprintln`] instead to print error and progress messages.\n\n# Panics\n\nPanics if writing to [`io::stdout`] fails.\n\n# Examples\n\n```rust\nprintln!(); // prints just a newline\nprintln!(\"hello there!\");\nprintln!(\"format {} arguments\", \"some\");\n```"
    },
    "range": {
        "start": {
            "line": 16,
            "character": 4
        },
        "end": {
            "line": 16,
            "character": 11
        }
    }
}

ocamllsp use ```ocaml

[Trace - 5:32:27 PM] Received response 'textDocument/hover - (7)' in 1ms.
Result: {
    "contents": {
        "kind": "markdown",
        "value": "```ocaml\ntype inlayHint = {\n  position : position;\n  label : string;\n  kind : int;\n  paddingLeft : bool;\n  paddingRight : bool;\n}\n```"
    },
    "range": {
        "start": {
            "line": 10,
            "character": 0
        },
        "end": {
            "line": 16,
            "character": 1
        }
    }
}

[Minnozz]

• https://code.visualstudio.com/api/references/contribution-points#contributes.grammars
• https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#embedded-languages

rescript-vscode/package.json

Lines 161 to 177 in 9d7573c

	"grammars": [
	{
	"language": "rescript",
	"scopeName": "source.rescript",
	"path": "./grammars/rescript.tmLanguage.json"
	},
	{
	"scopeName": "markdown.rescript.codeblock",
	"path": "./grammars/rescript.markdown.json",
	"injectTo": [
	"text.html.markdown"
	],
	"embeddedLanguages": {
	"meta.embedded.block.rescript": "rescript"
	}
	}
	],

I can't find any reference to res here, should that name also be registered in some way?

[Minnozz]

Ah, here:

rescript-vscode/grammars/rescript.markdown.json

Line 12 in 9d7573c

"begin": "(^|\\G)(\\s*)(\\`{3,}|~{3,})\\s*(?i:(res|rescript)(\\s+[^`~]*)?$)",

[aspeddro]

I've been exploring this issue using omd to format doc comments. Involves adding a dependency to the binary.