Roslyn: Showing <remarks> in QuickInfo results in very large tooltips for Xamarin

[sandyarmstrong]

Version Used: Version 16.6.0 Preview 2.0 [29918.199.master]

Steps to Reproduce:

1. Create new Xamarin.iOS single view project.
2. Open ViewController.cs.
3. Hover over UIViewController

Expected Behavior:

Actual Behavior:

---

This is the result of the (otherwise very useful!) https://github.com/dotnet/roslyn/pull/42135.

Mono and Xamarin historically make extensive use of <remarks> in documentation, and that information is typically kept intact for offline documentation (via the MonoDoc tool, see Help -> API Documentation on VSmac). Apparently, .NET Framework BCL documentation strips out <remarks> on user machines, but the data is available in online documentation.

VSmac has not yet inserted this week's Roslyn in order to avoid this issue on very basic types like System.Console and boolean literals:

(Of note, the above behavior only occurs for Mono-based projects on Mac, but that includes Xamarin.iOS, etc)

---

To be fair, it has always been possible to make unhelpfully large QuickInfo tooltips even before this change. While I feel that we do need to seriously address the problem over large tooltips, that should probably be a separate issue.

For now, we should decide how to move forward on showing <remarks> content. Some proposals:

1. Remove the feature entirely.
   This would be a bummer, as it seems generally useful. But maybe it's the right thing to do if QuickInfo UX needs some new design work.
2. Add an option for this feature, and disable it by default.
   This might be the best default behavior, but many people would never discover the option.
3. Add an option for this feature, enable it by default, but allow it to be disabled on a per-buffer level
   This would require additional work from the Xamarin and VSmac teams to keep it turned off for Mono-based workspaces/buffers/whatever. These users would miss out on the feature and have no way to force it on (unless the IDE added an additional option for that). I'm not personally familiar with how to implement this for Xamarin on VSwin.
4. Disable the feature for some specific namespaces, such as System.*, and perhaps UIKit.* and other Xamarin namespaces
   Seems reasonable for most Visual Studio users, but doesn't help scenarios where namespaces we don't know about have similarly lengthy <remarks>.
5. Truncate content to some "reasonable maximum"
   This seems problematic for the case of boolean literals in Mono. It is not especially helpful to show anything beyond a simple tooltip when mousing over false. And conversely, I would not want to over-truncate reasonable documentation.

Personally, I'd prefer 2 or maybe 3, to be followed by more general work on what to do about too-long QuickInfo content (regardless of <remarks>).

Prior art on huge tooltips: https://github.com/dotnet/roslyn/issues/21493

[CyrusNajmabadi]

Tagging @jinujoseph for visibility. We will have to do something here, though exact short term and medium term fixes are TBD.

[jasonmalinowski]

Add an option for this feature, and disable it by default.

That might also be a prudent option right away while we figure out a better setup. Then change the default once we did figure out something better.

[jinujoseph]

interesting, Sam did bring this concern in design meeting. Short term I think we should revert or put the feature behind experiment flag.

[sharwell]

I'm leaning back towards option 4 (excluding System.*). It's possible we just hit an outlier that would not be frequent in practice.

[jasonmalinowski]

I had one more idea for a very short term mitigation: what about limiting to only symbols from source? The challenge with symbols from metadata is they can't edit their <remarks> down, they're just stuck with it. At least things from source they have a workaround?

[sandyarmstrong]

@jasonmalinowski yeah that's an intriguing approach, too.

Here's one more idea: pick some arbitrary acceptable <remarks> length, and only show them if they are under that length. Could seem unpredictable to users in 16.6 but it would just be a stopgap until we solve the more general problem of long QuickInfo content (and we could put priority on that for 16.7).

[sandyarmstrong]

Also pinging @davidortinau (Xamarin PM) here so he can weigh in after .NET Conf: Xamarin.

[davidortinau]

Hi all, truncating sounds like a confusing experience for developers. I would much prefer to see this change reverted since it introduces a new and breaking behavior that wasn't foreseen. Can we please do that and come up with a solution that works for everyone?

[CyrusNajmabadi]

Hi all, truncating sounds like a confusing experience for developers.

Why would this be the case?

UI's truncate large pieces of information all the time. Seems super common and really easy for people to grok...

[sharwell]

We discussed this in the design review meeting and want to take the following approach:

1. Exclude System.*, which is what we intended to do from the start
2. Limit the number of _paragraphs_ that can be shown from remarks, which allows for reasonably long content provided it is organized in a way that isn't overwhelming to present

[sandyarmstrong]

Why would this be the case?

1. It's an overwhelming amount of data that distracts a user from their work. The beginning of a treatise on booleans or UIViewControllers is probably not that helpful.
2. There is no way to "expand" the truncated data, so if the truncated data _does_ seem helpful, it's not clear where to go to get the rest of it.
3. What do our UX designers have to say about increasingly large tooltips in the IDE?

Limit the number of paragraphs that can be shown from remarks, which allows for reasonably long content provided it is organized in a way that isn't overwhelming to present

This is also problematic. Then it's not even clear that the content is truncated, so it may terminate in what feels like a really random place.

---

I think we just need to realize that many <remarks> were not written with this in mind. Xamarin's certainly weren't. If we're not turning this off by default or disabling it completely, we need to add more exclusions for Xamarin until the more general issue of long QuickInfo content is addressed.

[sandyarmstrong]

And from Xamarin.Android, here's a before:

And after:

Aside from the issue of increased width, this tooltip is now dominated by licensing information. This was clearly intended for a page of documentation and not inline help.

[sandyarmstrong]

An exhaustive list of namespaces provided by Xamarin can be found here:

• https://github.com/xamarin/apple-api-docs/tree/master/en (very long list)
• https://github.com/xamarin/android-api-docs/tree/master/docs
• https://github.com/xamarin/Xamarin.Forms-api-docs/tree/master/docs (this one's easy, it's Xamarin.Forms.*)

Here's a Xamarin.Forms example where it's clear how inappropriate the content is out of the context of a doc viewer or doc website.

Before:

After:

The last sentence implies content to follow which is just missing from the point of view of the developer.

[sharwell]

This is also problematic. Then it's not even clear that the content is truncated, so it may terminate in what feels like a really random place.

It would end with a complete paragraph, followed by a separate line something like this:

_Additional remarks were truncated..._

[sandyarmstrong]

@sharwell ah, thanks for the clarification, that is certainly better. But the Xamarin.Android and Xamarin.Forms examples above are presumably short enough to not be truncated and are still clearly problematic. We'll just have to add more exclusions.

[CyrusNajmabadi]

There is no way to "expand" the truncated data, so if the truncated data does seem helpful, it's not clear where to go to get the rest of it.

Why not? You can always 'goto def'. We could alo have a hyperlink to just do this in the tooltip :)

[CyrusNajmabadi]

But the Xamarin.Android and Xamarin.Forms examples above are presumably short enough to not be truncated and are still clearly problematic. We'll just have to add more exclusions.

Sorry, can you clarify why they're 'clearly problematic'. As a reader, those docs look great. I'd much rather have the expanded version, with the useful information than the condensed form which tells me practically nothing...

[CyrusNajmabadi]

Aside from the issue of increased width, this tooltip is now dominated by licensing information. This was clearly intended for a page of documentation and not inline help.

That's a problem with the page of documentation as well. i would not want that at the top when reading the docs. I would expect that to be at the bottom, with the docs organized from most relevant to least relevant info.

[sandyarmstrong]

Sorry, can you clarify why they're 'clearly problematic'.

• "The last sentence implies content to follow which is just missing from the point of view of the developer."
• "this tooltip is now dominated by licensing information. This was clearly intended for a page of documentation and not inline help."

I'm not sure what else to say here. Before the tooltip showed what the doc developers wanted it to show. Now it does not. This is not the experience that was intended.

[sharwell]

I'm with Cyrus on the interpretation of the later examples. For both the Android.App example (https://github.com/dotnet/roslyn/issues/42606#issuecomment-604071976) and the Xamarin.Forms example (https://github.com/dotnet/roslyn/issues/42606#issuecomment-604076911), the new behavior seems like exactly what we want. The action item here is to update the documentation comments to not include website-specific content which will then ship as API documentation alongside the packaged assembly.

[CyrusNajmabadi]

I'm not sure what else to say here. Before the tooltip showed what the doc developers wanted it to show. Now it does not.

But it shows me what i want to see as a developer. This is why i want 'remarks'. They're useful docs. They contain the information i need. The summary is rarely good enough. It's often little more than a repeat of what the name already tells me (or is so vague as to not be helpful).

These examples demonstrate it. The existing docs are useless to me as the actual developer. And i think quick info should cater to the developer, not the writer. i.e. it's for the consumer's benefit, not hte producers.

[sandyarmstrong]

the new behavior seems like exactly what we want

Who is "we" in this case? It is not what the Xamarin team wants and is not what the documentation writers intended.

The action item here is to update the documentation comments to not include website-specific content which will then ship as API documentation alongside the packaged assembly.

There is a cost here to do this and still allow the API documentation to be available offline. I have no idea if this is realistic to occur in the 16.6 timeframe.

If this feature depends on documentation changes, it should not ship until those documentation changes are ready.

[CyrusNajmabadi]

Who is "we" in this case? It is not what the Xamarin team wants

1. Why do your desires override my desires as the person consuming the docs?
2. If you really want this level of control over the doc experience, it may be the case that it's better to build your own doc experience. As a VS user i find it super frustrating that a doc writer would tell me that i shouldn't look at the very docs they're writing even though i find it useful.

If this feature depends on documentation changes, it should not ship until those documentation changes are ready.

I disagree. For example, if you change the docs to remove htat useful information from the remarks, then it's just hurting me as a dev again. Once again i have to go somewhere else to find exactly the info i need... :-/

[sandyarmstrong]

Why do your desires override my desires as the person consuming the docs?

Neither of our desires matter much here. The Xamarin PM makes the call about what the best experience is for Xamarin developers.

[sharwell]

FWIW I agree with @sandyarmstrong that the CC AL license notice isn't what we want on that particular screen.

In either case, the _extraneous_ content for these cases is minimal to the point that it wouldn't be overwhelming, and perhaps wouldn't even be noticed by readers.

[CyrusNajmabadi]

The Xamarin PM makes the call about what the best experience is for Xamarin developers.

That's fine. I think if xamarin wants a distinctive documentation experience, it would likely be best to maybe have that responsibility move over to xamarin team then. That way you can cater this appropriately as best as you think makes sense for your audience.

[sharwell]

One easy way to resolve this from the Xamarin side prior to a more comprehensive approach is to filter the XML files in the SDK packages to not include <remarks> elements. This approach would match the approach used for .NET reference assemblies.

[tamlin-mike]

An option I haven't seen mentioned yet is to borrow how this works from IntelliJ. On first quick-info invocation you get the short version. If you invoke it again, you toggle (meaning you can toggle small-large-small-...) to a different view displaying all info. That second view is (IIRC), while floating, a full-fledged text view with scrollbar and so on.