Dotnet-api-docs: Document System.PlatformNotSupportedException on .NET Core?

[b8adamson]

Should this be included in the list of Exceptions?

---

Document Details

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

• ID: 3a8ddcfc-735a-b44c-ad27-7b84f2e21e76
• Version Independent ID: 56f5b699-5568-9d50-e720-b02d8015e007
• Content: Assembly.ReflectionOnlyLoadFrom(String) Method (System.Reflection)
• Content Source: xml/System.Reflection/Assembly.xml
• Product: dotnet-api
• GitHub Login: @dotnet-bot
• Microsoft Alias: dotnetcontent

[mairaw]

We do have a broad issue where we plan to add this information (see #1683) but this API/namespace is not listed in our reference wiki for some reason.

@kouvel do you know if there's someone maintaining that list or if we should add the System.Reflection namespace there at least?

But the answer to your question is yes @b8adamson if that API is throwing a PlatformNotSupportedException in .NET Core.

[mairaw]

And this is how we're adding that info to the docs if you want to create a PR and add that to this member:
https://docs.microsoft.com/en-us/dotnet/api/system.threading.thread.abort?view=netframework-4.7.2#System_Threading_Thread_Abort

https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading/Thread.xml#L584

[kouvel]

I'm not sure if the list in https://github.com/dotnet/corefx/wiki/ApiCompat is being maintained, my guess is that it would not be up to date. The area owners may be able to help with providing missing info.

[IanKemp]

Why does this documentation page exist at all for .NET Core, considering that the current implementation is specified to always throw a PlatformNotSupportedException?

[IanKemp]

It gets better: this document suggests that not only will Assembly.ReflectionOnlyLoadFrom never be implemented, but that users who require this functionality should be using the .NET Standard-only System.Reflection.TypeLoader instead.

[mairaw]

Because the reflection process can't see implementation details, so it displays what's available for each platform. There's a big gap at the moment for having these docs reflect .NET Core information and how that information comes from the dev team to docs.

/cc @karelz

[IanKemp]

Is there anything that we as the community can do to assist in closing that gap? Documentation has always been the area where Microsoft has had the competition beat, and I don't believe that Core's increased release cadence should change that.

[mairaw]

Sure @IanKemp! The community can help by documenting the ones already identified by the wiki: https://github.com/dotnet/corefx/wiki/ApiCompat

I'm also going to ask if we can get help from our vendor team on documenting those.

I agree that we need to close that gap ASAP.

[karelz]

@mairaw I really, really hope we will have time to invest into docs catch up with the new team members starting in upcoming weeks.

[mairaw]

That's great to hear @karelz! But I also think we need to come up with a better way of flagging API changes that have doc impact. It's hard to track those down nowadays.

[karelz]

@mairaw I don't disagree. One problem at a time. First catch-up, then future proof plan.

[IanKemp]

I would like to add a separate "version" of this page, that is only displayed for .NET Core and Standard, that indicates this method always throws PlatformNotSupportedException and that consumers should use System.Reflection.TypeLoader instead. Is there any way to do this?

[mairaw]

@IanKemp we don't currently have different versions of each API page (although this feature might be coming in the future).

The solution would be to add the exception similar to what we've done here:
https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Threading/Thread.xml#L584

You could either add a note to the remarks or just complement the exception info with the API recommendation.