XML comments and shorthand "///" comments do not always appear in quick-info tooltips in VS2017

[abelbraaksma]

I tested this with the latest VS2017 Preview 4.

The XML comments or the shorthand comments that generate quick-info information are invaluable, but since VS2017, through to Preview 4, they sometimes appear, and sometimes don't.

It seems to happen only when the declaration is in a different project in the same solution (both are F# projects). The tooltip shows correctly in the home project (the one it is declared in) but not in the host project (the using project).

Declaration:

In a using project:

Repro steps

I have tried to repro this with smaller projects linking each other, but each time I do that, it just works. So no repro yet.

Expected behavior

Quick-info tooltips should show the XML comment.

Actual behavior

Often tooltips do not show the XML comment.

Note that in this particular project, there seems to be no line in what gets rendered into the tooltip and what not. I checked:

• Whether the comment actually contains XML
• Whether the it's a type, a module, a let-binding, a value, a discriminated union type, a discriminated union field
• Clean - rebuild
• Restart VS

None of these seemed to matter. Sometimes the comment is shown, sometimes it is not. I thought it might have to do with background processing (sometimes you see the "..." in the intellisense dropdowns, but once these are gone, the actual tooltip is still without XML comment rendering.

Known workarounds

Falling back to VS2015 helps, it has no problems with the quick-info tooltips.

Other than that, no workarounds found any yet. I'd be very eager to hear whether I can clean some specific cache files or anything to fix this.

Related information

• Win7, Visual Studio 2017 Preview 4
• Project uses FSharp.Core 4.4.0.0.
• .NET 4.6 (CLR version: v4.0.30319)

Maybe not a big bug, but rather annoying as in this (and other) big projects I rely heavily on the these quick-infos.

As an aside and a compliment: using F12 hardly ever worked in VS2015, not even within the same project, but it always succeeds in VS2017, so: chapeau! and a big thank you! for the developers, it mitigates this issue a little as I can more easily go to the definition and check the XML comments there.

[dsyme]

I've noticed this bug too. I think it's a side effect of in-memory cross-project references being enabled in VS2017. I presume the same problem happens in Ionide and Rider.

master now has an explicit option to turn off cross-project references and rely on compiled DLLs. #3328 If you could try to use that to de-activate them and see if it fixes the problem we'd be grateful.

[abelbraaksma]

master now has an explicit option to turn off cross-project references and rely on compiled DLLs. #3328

@dsyme: I would if I could, I've been trying to move to the new F# RTM version, but so far unsuccessfully, too many compile errors, VS2017 acting up and some projects simply load 4.4.0.0 after I add 4.4.1.0 with NuGet. Probably binding issues, but it will take a while before I have this fixed.

Problems that I encounter that I consider regression issues (i.e., something compiles fine in F# 4.4.0.0 but not in F# 4.4.1.0) I'll report them separately.

[dsyme]

@abelbraaksma Thanks for taking the time to report these things

[dsyme]

Notes on the cause of this bug.... First, these are returning false:

    member x.HasDirectXmlComment =
        match x with
        | FSMeth(g,_,vref,_) -> valRefInThisAssembly g.compilingFslib vref

Second, the XML docs aren't actually being stored in the F# metadata for in-memory project references. Only the XML doc signature is stored. There is an expectation that there is an actual on-disk XML file that will be used by Visual Studio and other clients to actually fetch the information.

      entity_xmldoc=XmlDoc.Empty;
      entity_xmldocsig=x10;

The fixes would be

1. store the XML doc information in the TAST pickled metadata when doing in-memory compilation of a dependent project. This needs care though because we can't change the format in the on-disk case.

2. make HasDirectXmlComment return true for symbols coming from in-memory compilations

[abelbraaksma]

master now has an explicit option to turn off cross-project references and rely on compiled DLLs.

@dsyme: I've installed the latest nightlies, and I can see the settings in the options dialog box from the referenced issue, but even after waiting several hours, none of the functions, values, constants, methods I checked had its XML docs (simple or complex) filled. The types were parsed though and clickable in the quickinfo tooltips.

Before I installed the nightlies I used a fresh VS 2017 15.3.1.0 Preview 1 release, and sometimes the comments worked, sometimes they didn't.

I really miss them, so if there's anything I can do to help analyze this, like send in logs or something, please let me know.

[dsyme]

@dsyme: I've installed the latest nightlies, and I can see the settings in the options dialog box from the referenced issue, but even after waiting several hours, none of the functions, values, constants, methods I checked had its XML docs (simple or complex) filled.

Did you restart VS?

[abelbraaksma]

@dsyme, it seemed that I misinterpreted how the new options from @vasily-kirichenko's fix in #3330 work. Now that he gave an excellent explanation I can now confirm that:

• after switching OFF the setting for Enable in-memory cross-project references, then rebuilding, then closing and reopening the solution, the QuickInfo tooltips show the documentation again.
• when it is switched to ON, the documentation in the tooltips disappears.
• rebuilding the solution will remove the documentation from the tooltips, only VS restart shows them again.

About your earlier comment:

The fixes would be

1. store the XML doc information in the TAST pickled metadata when doing in-memory compilation of a dependent project. This needs care though because we can't change the format in the on-disk case.
2. make HasDirectXmlComment return true for symbols coming from in-memory compilations

This seems to be quite a tough one to fix? So I would assume that, provided you need those comments to work, users should get accustomed to restarting Visual Studio after each build, if you need the tooltips?

Perhaps there's a way we can use the on-disk assemblies and reload them when they are changed? This would prevent users to have to restart VS all the time.