Docs: .NET Standard 2.0 seems to be missing from "Applies to"

[gjkhw]

I can see that this API (WriteAsync) is visible from .NET Standard 2.0 classes, but it's not listed under "Applies to" in this documentation. Since 2.0 is a superset of 1.6, it should be in "Applies to". That would allow it to be browseable from the documentation browser with ".NET Standard 2.0" set as the filter.

It was confusing to me, because at first I thought that there was no Async Write api for .NET Standard 2.0.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: d5e9ff50-01f5-9915-94c7-eec4c7cc99c1
• Version Independent ID: 45f48724-5bb4-92a7-7a32-1b3afc011466
• Content: NetworkStream.WriteAsync(Byte[], Int32, Int32, CancellationToken) Method (System.Net.Sockets)
• Content Source: xml/System.Net.Sockets/NetworkStream.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[mairaw]

That information is based in the reference assemblies that we use but I can also see that apisof.net also shows the same version information for this API:
https://apisof.net/catalog/System.Net.Sockets.NetworkStream.WriteAsync(Byte(),Int32,Int32,CancellationToken)

@terrajobst @weshaggard do you have more context on this specific API and why it shows as dropped from .NET Standard 2.0?

[mairaw]

The diff file between 1.6 and 2.0 also seems to show that information being correct:

So I'm closing this doc issue. @davidsh or @karelz might also know the reason.

For questions on why the changes were made, I'd probably ask that on the dotnet/standard repo.

[terrajobst]

The API in question is an override. It looks like we no longer override the method in .NET Standard 2.0, hence it shows up a as missing.

For overrides, you need to consider the original definition, which in this case is Stream.WriteAsync. And that one shows up as present:

• https://docs.microsoft.com/en-us/dotnet/api/system.io.stream.writeasync?view=netframework-4.7.2#System_IO_Stream_WriteAsync_System_Byte___System_Int32_System_Int32_System_Threading_CancellationToken_
• https://apisof.net/catalog/System.IO.Stream.WriteAsync(Byte(),Int32,Int32,CancellationToken)

[svick]

I understand that the documentation is technically accurate, but I also think that it's confusing, because it does look like the method was removed from .Net Standard 2.0.

Maybe there could be a rule that if a method is overridden in at least one framework, its Applies To section will contain all frameworks that have both the base method and the derived type?

[karelz]

@terrajobst I agree that the docs are confusing. Is there something we can do? Maybe diff all "removed" overrides and explicitly make them show up as "applies to"?

[terrajobst]

Is there something we can do? Maybe diff all "removed" overrides and explicitly make them show up as "applies to"?

Let's walk the list of options.

Fixing at the catalog level. We could try to address the mismatches in overrides by either (1) removing all overrides from reference assemblies or (2) mark all methods as overriden all the time. The latter is probably worse in terms of noise and bloat, so I believe only the former is viable. However, there are many cases where one wants to put documentation on specific overrides, so I'd consider removing those a non-starter too.

Fixing the display of Applies To. In order for this to be correct, the catalog would have to mark an API as available if (1) the API is present or (2) it's an override and the original definition is present. Unfortunately, we don't have that information in the catalog. I can try and investigate whether that's feasible but I'm not sure I'l have the cycles any time soon...

[gjkhw]

Does it make sense to reopen this issue? If there are no cycles to work on it now (while it's closed) I am afraid it will be ignored. I get the feeling that there are a lot of APIs that people are going to miss when programming against .NET Standard that they needn't.