Implement Quick Info styles

[sharwell]

• Support emphasis in Quick Info (<em> and <i> elements in XML documentation comments)
• Support strong in Quick Info (<strong> and <b> elements in XML documentation comments)
• Support code font in Quick Info (<c>, <code>, <tt> elements in XML documentation comments)
• Support bullet and numbered lists in Quick Info
• Support definition lists in Quick Info
• Support navigating to cref items by clicking in Quick Info
• Support navigating to href hyperlinks in Quick Info (<see href and <a href)

Images

⚠️ This picture is slightly outdated relative to current behavior (both links to https://google.com now render correctly, and the spacing for list items has changed slightly.

[CyrusNajmabadi]

def not liking this.

1. symbolkey shoudn't be throwing.
2. not happy about all this sync blocking. can we not be async here?

Worst case, when someone navigates, we can do a TWD and make it cancellable if something goes off the rails.

[sharwell]

not happy about all this sync blocking. can we not be async here?

Limited by the editor API. @gundermanc how would you handle this?

[CyrusNajmabadi]

note: sync blocking is ok with me. it's more the lack of cancellability. That should hopefully be something we can fix up with a TWD.

[gundermanc]

I think the only option is to do whatever the equivalent of a Dispatcher.InvokeAsync() is in this layer. From the IDE side, we usually use JTF.RunAsync(). I understand this is the portable editor features, so, there likely is no dispatcher.

For my own edification, would it be preferable to have actions like this be async? I didn't think it was necessary originally because we're de facto going to have to InvokeAsync() somewhere but I acknowledge things are a bit more constrained for Roslyn since this layer has to work on Mac.

[CyrusNajmabadi]

I'd be fine with this being async (which honestly makes sense to me given that any of thse clicks might cause major work to happen). Or, if sync, at least have it be under a TWD.

[sharwell]

@CyrusNajmabadi @dotnet/roslyn-ide This is now ready for proper review

[CyrusNajmabadi]

could we consider extracting out everything above (into something like StartContainerElement(...))? I thnk it would make it much easier to understand things if we just had a top level lopo, with the high level decision making, and then have the individual functions that are responsible for each piece of work. intermingling them makes it harder to keep track and understand what's going on for me.

[CyrusNajmabadi]

could you doc this? when would you use ContainerEnd for example?

[sharwell]

Can we add href here?

I'll file a follow-up issue for this, and also for the other elements that are now supported by Quick Info.

When you use an entity that's invalid XML, like  , we previously showed a squiggle for CS1570.

I have not made any changes in this space. The compiler is in control of the scenario.

Spacing within <code> blocks is not preserved (multiple adjacent spaces or newlines).

This is a known limitation; will file a follow-up issue.

You can't type <c> to get a c tag

IntelliSense is not allowed to ever make this replacement. Can you describe how you encountered this?

Also can't type <a href for the same reason.

This is a side effect of not having a in the completion list. It will be covered by the issue that includes this and other newly-supported elements.

Clicking on a link created using <a href sometimes causes an assert:

This is a debug-only side effect of #35667 (comment), and covered by the same follow-up issue.

Matching close tags for new constructs are not offered after </

This is an IntelliSense bug unrelated to this pull request.

You can make numbered lists that start at 0. Not sure if bug or feature.

It's not a bug or a feature. It's Quick Info's current handling of unspecified behavior for an incorrectly-formed <list> element. I'm fine with this edge case.

[dpoeschl]

When you use an entity that's invalid XML, like  , we previously showed a squiggle for CS1570.

I have not made any changes in this space. The compiler is in control of the scenario.

In the non-inheritdoc scenario, this is fine. I had inconsistent settings between test projects for generating the xml doc files. I'm not positive about the inheritdoc scenario.

[dpoeschl]

👍

[sandyarmstrong]

@sharwell is it already a known issue that there there is no completion item for "href" or "a" when writing XML doc comments?

EDIT: OK, I see #37504 now, nevermind!

[vancura]

Please, why don't you use semantically correct classnames, which are independent of the styling? <strong>, <em> and similar are too connected to the form/styling. It would be better to learn from the HTML/CSS world (when CSS is semantically correct) and use independent tokens.

This is where I am coming from (I am designer of VSMac, VS and VSCode):

See mainly on the right-hand side: just about this week I wanted to prepare a couple of comps on all our platforms how this output could work, and then propose a Roslyn JSON/XML output which could be then parsed and styled by the target application. Do you think your new output format could potentially do this, too?

I am slightly nervous that Roslyn will recommend where the design should use bold, italics, and other stylistic treatments. This should be up to the target application (and the designer of it) to decide.

Thoughts?

[vancura]

Hm, I see it's too late to complain, this was already merged (I learned about the feature just a couple of minutes ago).

Let's see how much can we parse and style the output in our products even with the style tags around.

[CyrusNajmabadi]

Please, why don't you use semantically correct classnames, which are independent of the styling?

Could you clarify who you are asking here? It's not clear to me what change you are asking for.

I am designer of VSMac, VS and VSCode

Sounds like something you could drive improvements in :)

[sharwell]

@vancura This pull request does not require the use of any specific tags. It does not add the items to IntelliSense where users would be encouraged to use them. The only thing it does is apply styling in the IDE for users who already were using these elements, and for those users the style it is now showing matches the style they expected.

[sharwell]

It's not clear from your screenshot what your question is. Here's a copy of your screenshot showing the section of the Quick Info popup which is covered by this pull request. Note that the only change to the first line is the use of hyperlinks.

[sharwell]

@vancura Please include me in the discussion of documentation formats. I need to make sure the proposal will work with existing documentation produced by the compiler as well as post-processing tools like Sandcastle Help File Builder, and also works with proposals like dotnet/csharplang#891 with ongoing design work in https://gist.github.com/sharwell/ab7a6ccab745c7e0a5b8662104e79735.

[vancura]

@sharwell Thank you for the clarification! I will draw a couple of pictures from all the products, so we have something to look at, and then it would be good to have a short talk on what we can do. Thanks! :)