Improving doc comments syntax highlighting in hovering

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.

@zth

CC @zth @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.

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.

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
        }
    }
}

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?

Ah, here:

rescript-vscode/grammars/rescript.markdown.json

Line 12 in 9d7573c

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

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

Navigation Menu

Repository navigation

Improving doc comments syntax highlighting in hovering #545

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	"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"
	}
	}
	],

Improving doc comments syntax highlighting in hovering #545

Description

Activity

cristianoc commented on Aug 4, 2022

ryyppy commented on Aug 4, 2022

ryyppy commented on Aug 4, 2022

aspeddro commented on Aug 4, 2022

Minnozz commented on Aug 6, 2022

Minnozz commented on Aug 6, 2022

aspeddro commented on Nov 5, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions