[bracketed references] in dartdocs are not highlighted as code in tooltips

[FrobtheBuilder]

I know that using bracketed names in your dartdoc documentation is a way to refer to symbols, correct? But the popup documentation produced by hovering on a symbol just naively displays them in the same font as the rest of the text, brackets and all. Shouldn't it at least say, format those names with a monospaced font as you typically want with symbols and maybe exclude the brackets or draw them in a lighter color? It's just a bit ugly right now. You can manually format text as code using backticks, but then you can't hover over the names in the dartdoc block to see their own documentation.

I see the formatting I'm looking for in the example cited in #1265 but the editor used there appears to be Android Studio, so this is a feature in that IDE. It would be nice to have it in vscode as well.

Example:

[DanTup]

Unfortunately I had to remove the code that was doing this, because it was also messing up code blocks. For example:

/// [foo]
///
///    var foo = "test";
///    var a = [foo] ;

Here, the first [foo] we'd like to replace with `foo` so it's coloured correctly, but the second we do not (because the sample code would be invalid). To the editor, this is just a string of markdown and we don't do additional parsing to understand which bits are code and which are not (we probably could, but I worry it'd be fragile given how often we find weird cases in code syntax highlighting).

@devoncarew @bwilkerson can you think of any simple solution to this?

[bwilkerson]

Given the following code

/// [foo]
///
///    var foo = "test";
///    var a = [foo] ;
main() {}
foo() {}

server will create a navigation region for the first foo, but not for the second. (I didn't check for highlighting regions.)

Would it be possible to use the navigation (or highlighting?) regions to differentiate between those two cases?

[DanTup]

@bwilkerson interesting idea, though I don't think from the documentation on a hover request we have the necessary info to map it back to a specific source location (we don't have the offset of the docs - which would be in another file - and the docs we get have had the comment markers stripped).

[bwilkerson]

Oh, right. I hadn't fully understood the conditions. I agree, you don't have enough information at that point.

We've talked before about having server support different formats for the hover information (markdown, html, etc.), and that might solve the problem. Unfortunately, that work hasn't been a high enough priority to get resourced.