System.IO.Ports.SerialPort has no IntelliSense documentation

[ygoe]

Description

The SerialPort class and its members are completely undocumented within Visual Studio.

Reproduction Steps

• Install the System.IO.Ports NuGet package
• Create an instance of the SerialPort class
• Browse its members in the C# code editor

Expected behavior

Some documentation

Actual behavior

No documentation

Regression?

No response

Known Workarounds

Probably some information can be found online

Configuration

.NET 6.0 project, .NET 7.0 package, VS 2022 17.4.1 on Windows 10 x64

Other information

Other inline documentation works great, from within the project and from other packages and the BCL

[ghost]

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Description

The SerialPort class and its members are completely undocumented within Visual Studio.

Reproduction Steps

• Install the System.IO.Ports NuGet package
• Create an instance of the SerialPort class
• Browse its members in the C# code editor

Expected behavior

Some documentation

Actual behavior

No documentation

Regression?

No response

Known Workarounds

Probably some information can be found online

Configuration

.NET 6.0 project, .NET 7.0 package, VS 2022 17.4.1 on Windows 10 x64

Other information

Other inline documentation works great, from within the project and from other packages and the BCL

Author:	ygoe
Assignees:	-
Labels:	area-System.IO
Milestone:	-

[krwq]

I confirm there is no intellisense data. I'm also not seeing XML docs in the code... cc: @carlossanlop

[krwq]

Per offline conversation with @carlossanlop that should work and we should be picking up xml docs from dotnet-api-docs. For some reason that's not happening. We should aim to fix this in 8.0 timeline.

[krwq]

@carlossanlop you mentioned offline this might be already fixed by unrelated PR of yours. Can you confirm?

[krwq]

FWIW it's still not showing for me:

What's the timeline for the intellisense data to be uploaded assuming this is fixed already?

[carlossanlop]

I checked, and the System.IO.Ports assembly uses both GeneratePlatformNotSupportedAssemblyMessage and IsPartialFacadeAssembly, which are special cases that my unrelated PR did not fix. We will address this at a later time.

[carlossanlop]

I tested the System.IO.Ports package in VS, and noticed that IntelliSense was still working in nuget package version 6.0.0-rc.1.21451.13 (published on Sept 14 2021), and stopped working in version 6.0.0-rc.2.21480.5 (published on Oct 12 2021).

This probably happened due to some refactoring changes in our infrastructure. I'm unsure about the dates (because we were snapping RC1/RC2), but I tentatively found #58558 and #58011 as potential suspects. Other suspects are 9722a6a , 21e340d and 85441ce.

The current logic is broken for two scenarios: When the assembly generates "PlatformNotSupportedException", or when the assembly is a partial facade assembly. Unfortunately for System.IO.Ports, it enables both properties.

This is how we decide which intellisense xml we should ship to customers:

• We download the internal intellisense nuget package that gets built by dotnet-api-docs, which is currently our source of truth for documentation. The documentation included in that package is correct: System.IO.Ports.xml contains all the expected documentation for that assembly.
• We build the runtime libraries. The normal build process generates an intellisense xml file, but since it contains information from triple slash comments, and we don't consider it the source of truth yet, we replace that file with the equivalent xml file contained in the nuget package.
• After the infra refactorings mentioned above, it seems we stopped doing the xml substitution in OOB packages, and instead we just shipped the xml generated during the build, which, in the case of System.IO.Ports at least, it contains only information from exception resource strings, due to the PNSE property being enabled.
• My recent "unrelated PR" added a new property that can be used in src csproj files that are not using PNSE or Facade assemblies, and use their own built xml instead of copying the one that comes from the nuget package. Adding this property to System.IO.Ports would not work since it generates only SR strings in the built xml.

So the next step is to figure out if it is possible to overwrite the xml generated by System.IO.Ports (and other OOB assemblies with a similar issue) with the dotnet-api-docs xml. There's a chance that this is another symptom of either the PNSE or the Partial Facades problem, which are not trivial to solve.

[ghost]

Tagging subscribers to this area: @dotnet/area-infrastructure-libraries
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Description

The SerialPort class and its members are completely undocumented within Visual Studio.

Reproduction Steps

• Install the System.IO.Ports NuGet package
• Create an instance of the SerialPort class
• Browse its members in the C# code editor

Expected behavior

Some documentation

Actual behavior

No documentation

Regression?

No response

Known Workarounds

Probably some information can be found online

Configuration

.NET 6.0 project, .NET 7.0 package, VS 2022 17.4.1 on Windows 10 x64

Other information

Other inline documentation works great, from within the project and from other packages and the BCL

Author:	ygoe
Assignees:	-
Labels:	bug, documentation, area-Infrastructure-libraries
Milestone:	6.0.x

[carlossanlop]

We have fixed the underlying issue affecting OOB packages:

• main Copy local intellisense xmls for assemblies with source of truth. #79134
• 7.0 [7.0] Fix intellisense xml file selection from 'net' or 'dotnet-plat-ext'  #82554
• 6.0 [6.0] Fix intellisense xml file selection from 'net' or 'dotnet-plat-ext' #82562

The next time any of these affected OOB packages gets a servicing fix and we enable it for building, the intellisense xml will contain the full docs as expected.