[doc] dart template:top VS Code hover highlight support

[dcharkes]

Currently, when doc comments contain code snippets with the following,

///```dart
///```

all of our tooling supports this.

However, when using the following, the VS Code highlighter doesn't support this.

///```dart template:xyz
///```

https://github.com/dart-lang/sdk/blob/d45ae603f7a25fb8a3df731b1078c8582afc5ee5/sdk/lib/ffi/ffi.dart#L866-L869

Hover without the template

cc @lrhn @DanTup

templates introduced in 44baaf13b6336fd4c5da0282dbd7514d99c00539.

[DanTup]

@dcharkes sorry, I didn't see this until now.

Is this syntax something standard, or created by Dart/dartdoc?

///```dart template:xyz
///```

The hover tootlips are interpreted by VS Code. It understands triple-backtick blocks (and the language ID) and applies colouring. The VS Code extension/analysis server aren't involved at that point. If it's some standard that VS Code isn't handling, we could file a bug there. If it's something Dart/dartdoc created but is not standard, we'd need to parse the markdown to find these blocks and strip the extra template:xyz part before sending that dartdoc to the client (similar to the special handling of @template/@macro). (fyi @bwilkerson @srawlins)

[dcharkes]

If it's something Dart/dartdoc created but is not standard, we'd need to parse the markdown to find these blocks and strip the extra template:xyz part before sending that dartdoc to the client.

I believe it is not standard, I've never seen it before in any other tool.

[bwilkerson]

I'm fairly sure that it's non-standard. We have added the extra information so that we could analyze the code samples to help ensure the correctness of the code snippets. Stripping everything past the language name seems like a reasonable solution to me.

As another datapoint, IntelliJ appears to ignore anything after the first whitespace ending the language name. However, IntelliJ doesn't appear to do any syntax highlighting in hovers even without the following material.

[srawlins]

I don't believe it's a dartdoc syntax.

[DanTup]

Yep, I misunderstood the original change. I thought it was for improving dartdoc output, but as Brian noted, it's for validating the code snippets within the SDK.

Would just stripping these from the entire dartdoc with a regex be good enough? I don't know if it's possible to have \n?```dart foo\r?\n in a place we wouldn't want to strip foo, but I don't think right now we're actually parsing the markdown currently (it's something I'd like to do for some syntax highlighting fixes, but I think the parser needs some changes to support providing offsets/lengths).

[bwilkerson]

I haven't yet thought of a counter example where it would fail, so I suspect that a regex would be sufficient for almost all cases.

[lrhn]

The syntax is general markdown/commonmark, not something unique to Dart or DartDoc. It's traditional to use the first word of the info string as the language tag, and allow more text after it.

Maybe we could file an issue for VSCode to only use the first word?

Otherwise cutting off the rest of the info string before sending it to IDEs seems safe.

[DanTup]

@lrhn thanks! There are some examples on that page doing just this:

https://spec.commonmark.org/0.28/#example-112

So I think it's a fair VS Code request. I'll file an issue.

[DanTup]

I've filed github.com/microsoft/vscode/issues/157793. Please add 👍 's if you'd like to see this added (issues are often closed by a bot if there is not sufficient 👍 's within 60 days).

[DanTup]

This has been fixed in VS Code. Left is stable VS Code, right is VS Code Insiders. It should show up in the next stable release (VS code usually releases around one week into each month).