Make API documentation more version aware

[pkulikov]

Is it possible to make API documentation more version aware (.NET Core 1.0, .NET Core 2.0, etc)?

For example, look at MethodImplOptions enum for .NET Core 1.0. The note in Remarks looks a little bit alien as there is no Synchronized flag in .NET Core 1.0. That value appears only in .NET Core 2.0. So, remarks also might differ from version to version.

[mairaw]

I think there are two parts to this:

1. Having a way to do conditional content dependent on platform and version
2. Identify where those differences are and change the content appropriately

I think for item 1, we have a plan to add that capability in the future. For 2, we try to mindful of that for new or updated content in the text, but there's a lot of content that was simply migrated from MSDN as-is. It's a tricky issue to solve.

[Powerhelmsman]

@dend Can decide if we will resolve the issue?

[svick]

@mairaw I think identifying the differences could be automated. I imagine it would work like this:

• Step 1: For each member, find on which frameworks it is present. I think <AssemblyInfo> should help with that. Though is there a mapping between assembly name+version and framework somewhere? _moniker2Assembly.json does not contain versions, so it's not enough.
• Step 2: Look for references (both xref and plaintext) to those members in text that is shown for frameworks that don't contain them.

This approach is likely going to have both false positives and false negatives, but I think it could still be helpful.

[dend]

@svick for the most part, I think the versioning infrastructure is in place - we use monikers when we reflect the assemblies, so we know which APIs are coming from where. Assemblies are not as helpful here, because they are not reflective of the version of the product all the time (e.g. older assembly used in both the new and the old release of a SDK).

Given that the content is for the most part hand-written for the .NET platform, this is something that @mairaw can implement directly in the XML files, with conditionals, where sections of the content are only available for certain monikers.

@Powerhelmsman let's keep this open until a resolution is in place!

[svick]

@dend

for the most part, I think the versioning infrastructure is in place - we use monikers when we reflect the assemblies, so we know which APIs are coming from where.

I understand that you know that. But how can I, as someone who might be interested in analyzing the API reference, learn that? <AssemblyInfo> is all I can see in the XML files.

[dend]

@svick good point - I have it on the radar to document mdoc (the tool that we use for our documentation) that outlines how we pull in different monikers in XML files. We should also document how versioning works inside Markdown content (since that is what you can use inside remarks).

[ermau]

Another example of this can be seen in the docs for HashSet. If you scroll down you'll find there's a note in the remarks how IReadOnlyCollection<T> was only added in 4.6. However, despite the selection of 4.5.2, it's still listed in the list of interfaces right at the top.

[Powerhelmsman]

#log-suggestion @dend

[supernova-eng]

🚀 ATTENTION: Internal request logged.

[mairaw]

@dend do you have something already logged to control which interfaces are shown for which version?

[dend]

@mairaw that is the work that @joelmartinez has done for FrameworkAlternate. That said, the suggestion above is a content ask, as we do not control how remarks are managed between different frameworks. I am closing this particular item, as it's not related to docs infrastructure work, and will defer to you to determine the path forward for .NET conditional content (e.g. using moniker zones).

[mairaw]

Just FYI to @pkulikov, we don't have this moniker zones capability yet.

@dend I still think there's some basic version awareness that needs to happen as well, which is related to the docs infrastructure. Showing the right attributes, the right signature, etc.