Port inheritdoc tags for APIs that are already fully documented

[carlossanlop]

This is a continuation of #8335 . Full explanation can be found there.
This PR includes the tags that were found in APIs that were already documented.

[carlossanlop]

@dotnet/area-extensions-caching @dotnet/area-extensions-configuration @dotnet/area-extensions-dependencyinjection @dotnet/area-extensions-filesystem @dotnet/area-extensions-hosting @dotnet/area-extensions-logging @dotnet/area-extensions-primitives @dotnet/area-system-buffers @dotnet/area-system-codedom @dotnet/ncl @HongGit @StephenMolloy @dotnet/area-system-runtime @dotnet/area-system-security @dotnet/area-system-text-json @dotnet/area-system-text-encoding @dotnet/area-system-xml @dotnet/area-system-globalization

[tarekgh]

@carlossanlop does this change include all inherit docs or just a subset of it? I am asking because I recall there were some of them in DateOnly and component model which not showing up here.

MS extensions and System changes LGTM.

[carlossanlop]

@tarekgh the main PR is this one: #8335, which contains the subset of APIs that are currently showing as undocumented in the report.

The rest of them are the ones you're seeing in this PR. They are the APIs that have already been fully documented in the past, by copying the strings from the base type or the interface.

[carlossanlop]

I'm investigating the warnings. I see the tool is porting some crefs with characters escaped, and that should not happen.

[BillWagner]

This LGTM @carlossanlop

Once the open conversations are resolved, you can

[gewarren]

The undoc APIs report we generate from MS Docs is also able to assume an API to be documented if it has the inheritdoc tag, and the parent is documented.
This PR ports the inheritdoc tag only for APIs that are partially or fully undocumented, so that they stop showing in the report.

Why do the APIs show up in the report if they are already documented?

[carlossanlop]

The undoc APIs report we generate from MS Docs is also able to assume an API to be documented if it has the inheritdoc tag, and the parent is documented.
This PR ports the inheritdoc tag only for APIs that are partially or fully undocumented, so that they stop showing in the report.

Why do the APIs show up in the report if they are already documented?

That's the description of the other PR, in which I am porting the inheritdoc tag of those APIs that were still partially or fully undocumented. So those are the ones showing up in the report.

This PR contains APIs that are already fully documented, but the tool also found they had the inheritdoc tag in triple slash. These aren't showing up in the report, I'm just porting them for completeness.

[carlossanlop]

The rest of the warnings are being checked by the Docs dev team, they seem to be a bug.

[gewarren]

This PR contains APIs that are already fully documented, but the tool also found they had the inheritdoc tag in triple slash. These aren't showing up in the report, I'm just porting them for completeness.

I wonder what mdoc would do in this case. Perhaps we should test.

[carlossanlop]

I wonder what mdoc would do in this case. Perhaps we should test.

You were right to raise the concern. If we add inheritdoc to an API with partial or full documentation, inheritdoc is ignored.

Example: The GUID operator "<=":

Here is the preview:
https://review.docs.microsoft.com/en-us/dotnet/api/system.guid.op_greaterthanorequal?view=net-7.0&branch=pr-en-us-8336

Here is the source file:
https://github.com/dotnet/runtime/blob/fe9a5a4685f1314bab48804ae9b9716890b331e1/src/libraries/System.Private.CoreLib/src/System/Guid.cs#L1302

Here are the partially documented docs:

dotnet-api-docs/xml/System/Guid.xml

Lines 1149 to 1156 in 83a7d69

	<Docs>
	<param name="left">To be added.</param>
	<param name="right">To be added.</param>
	<summary>Compares two values to determine which is greater or equal.</summary>
	<returns>
	<see langword="true" /> if <paramref name="left" /> is greater than or equal to <paramref name="right" />; otherwise, <see langword="false" />.</returns>
	<remarks>To be added.</remarks>
	<inheritdoc cref="M:System.Numerics.IComparisonOperators`3.op_GreaterThanOrEqual(`0,`1)" />

Here is the interface from which it should inherit automatically:

dotnet-api-docs/xml/System.Numerics/IComparisonOperators`3.xml

Lines 82 to 83 in 83a7d69

	<param name="left">The value to compare with <paramref name="right" />.</param>
	<param name="right">The value to compare with <paramref name="left" />.</param>

So I guess the Docs porting tool should strip all the existing documentation (except remarks) if it is going to add an inheritdoc. What do you think, @gewarren?

[opbld32]

Docs Build status updates of commit 914ecb3:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/Microsoft.Extensions.DependencyInjection/DefaultServiceProviderFactory.xml	💡Suggestion	View	Details
xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml	💡Suggestion	View	Details
xml/System.Net.Http.Headers/HeaderStringValues.xml	💡Suggestion	View	Details
xml/System.Net.Http.Headers/HeaderStringValues+Enumerator.xml	💡Suggestion	View	Details
xml/System.Net.Http.Headers/HttpHeadersNonValidated.xml	💡Suggestion	View	Details
xml/System.Net.Http.Headers/HttpHeadersNonValidated+Enumerator.xml	💡Suggestion	View	Details
xml/System.Text.Json/JsonElement+ArrayEnumerator.xml	💡Suggestion	View	Details
xml/System.Text.Json/JsonElement+ObjectEnumerator.xml	💡Suggestion	View	Details
xml/System/TimeOnly.xml	💡Suggestion	View	Details
xml/System/TimeSpan.xml	💡Suggestion	View	Details
xml/Microsoft.Extensions.Caching.Memory/MemoryCache.xml	✅Succeeded	View
xml/Microsoft.Extensions.Configuration/ChainedConfigurationProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Configuration/ConfigurationRoot.xml	✅Succeeded	View
xml/Microsoft.Extensions.Configuration/FileConfigurationProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.DependencyInjection/ServiceProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.FileProviders.Physical/PhysicalDirectoryInfo.xml	✅Succeeded	View
xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml	✅Succeeded	View
xml/Microsoft.Extensions.FileProviders.Physical/PollingWildCardChangeToken.xml	✅Succeeded	View
xml/Microsoft.Extensions.FileProviders/NotFoundFileInfo.xml	✅Succeeded	View
xml/Microsoft.Extensions.Hosting.Systemd/SystemdNotifier.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Abstractions/NullLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.EventSource/EventSourceLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.TraceSource/TraceSourceLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging/LoggerFactory.xml	✅Succeeded	View
xml/Microsoft.Extensions.Primitives/CancellationChangeToken.xml	✅Succeeded	View

This comment lists only the first 25 files in the pull request.

xml/Microsoft.Extensions.DependencyInjection/DefaultServiceProviderFactory.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:CreateServiceProvider(Microsoft.Extensions.DependencyInjection.IServiceCollection) for uid: Microsoft.Extensions.DependencyInjection.DefaultServiceProviderFactory.CreateServiceProvider(Microsoft.Extensions.DependencyInjection.IServiceCollection).

xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerable#GetEnumerator for uid: Microsoft.Extensions.FileProviders.NotFoundDirectoryContents.System#Collections#IEnumerable#GetEnumerator.

xml/System.Net.Http.Headers/HeaderStringValues.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IEnumerable{System#String}#GetEnumerator for uid: System.Net.Http.Headers.HeaderStringValues.System#Collections#Generic#IEnumerable{System#String}#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerable#GetEnumerator for uid: System.Net.Http.Headers.HeaderStringValues.System#Collections#IEnumerable#GetEnumerator.

xml/System.Net.Http.Headers/HeaderStringValues+Enumerator.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerator#Reset for uid: System.Net.Http.Headers.HeaderStringValues.Enumerator.System#Collections#IEnumerator#Reset.

xml/System.Net.Http.Headers/HttpHeadersNonValidated.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IEnumerable{System#Collections#Generic#KeyValuePair{System#String@System#Net#Http#Headers#HeaderStringValues}}#GetEnumerator for uid: System.Net.Http.Headers.HttpHeadersNonValidated.System#Collections#Generic#IEnumerable{System#Collections#Generic#KeyValuePair{System#String@System#Net#Http#Headers#HeaderStringValues}}#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IReadOnlyDictionary{System#String@System#Net#Http#Headers#HeaderStringValues}#ContainsKey(System.String) for uid: System.Net.Http.Headers.HttpHeadersNonValidated.System#Collections#Generic#IReadOnlyDictionary{System#String@System#Net#Http#Headers#HeaderStringValues}#ContainsKey(System.String).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IReadOnlyDictionary{System#String@System#Net#Http#Headers#HeaderStringValues}#TryGetValue(System.String,System.Net.Http.Headers.HeaderStringValues@) for uid: System.Net.Http.Headers.HttpHeadersNonValidated.System#Collections#Generic#IReadOnlyDictionary{System#String@System#Net#Http#Headers#HeaderStringValues}#TryGetValue(System.String,System.Net.Http.Headers.HeaderStringValues@).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerable#GetEnumerator for uid: System.Net.Http.Headers.HttpHeadersNonValidated.System#Collections#IEnumerable#GetEnumerator.

xml/System.Net.Http.Headers/HttpHeadersNonValidated+Enumerator.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerator#Reset for uid: System.Net.Http.Headers.HttpHeadersNonValidated.Enumerator.System#Collections#IEnumerator#Reset.

xml/System.Text.Json/JsonElement+ArrayEnumerator.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IEnumerable{System#Text#Json#JsonElement}#GetEnumerator for uid: System.Text.Json.JsonElement.ArrayEnumerator.System#Collections#Generic#IEnumerable{System#Text#Json#JsonElement}#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerable#GetEnumerator for uid: System.Text.Json.JsonElement.ArrayEnumerator.System#Collections#IEnumerable#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerator#Current for uid: System.Text.Json.JsonElement.ArrayEnumerator.System#Collections#IEnumerator#Current.

xml/System.Text.Json/JsonElement+ObjectEnumerator.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#Generic#IEnumerable{System#Text#Json#JsonProperty}#GetEnumerator for uid: System.Text.Json.JsonElement.ObjectEnumerator.System#Collections#Generic#IEnumerable{System#Text#Json#JsonProperty}#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerable#GetEnumerator for uid: System.Text.Json.JsonElement.ObjectEnumerator.System#Collections#IEnumerable#GetEnumerator.
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:System#Collections#IEnumerator#Current for uid: System.Text.Json.JsonElement.ObjectEnumerator.System#Collections#IEnumerator#Current.

xml/System/TimeOnly.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_Equality(System.TimeOnly,System.TimeOnly).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_GreaterThan(System.TimeOnly,System.TimeOnly).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_GreaterThanOrEqual(System.TimeOnly,System.TimeOnly).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_Inequality(System.TimeOnly,System.TimeOnly).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_LessThan(System.TimeOnly,System.TimeOnly).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeOnly.op_LessThanOrEqual(System.TimeOnly,System.TimeOnly).

xml/System/TimeSpan.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeSpan.op_Division(System.TimeSpan,System.Double).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeSpan.op_Division(System.TimeSpan,System.TimeSpan).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.TimeSpan.op_Equality(System.TimeSpan,System.TimeSpan).

This comment lists only the first 25 errors (including error/warning/suggestion) in the pull request.
For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

• Try searching the docs.microsoft.com contributor guides
• Post your question in the Docs support channel

[rzikm]

System.Net.* changes LGTM

[gewarren]

I wonder what mdoc would do in this case. Perhaps we should test.

You were right to raise the concern. If we add inheritdoc to an API with partial or full documentation, inheritdoc is ignored.

But isn't there a bug with inheritdoc on operators specifically?

It actually does seem to be working properly (here the value is inherited): https://review.docs.microsoft.com/en-us/dotnet/api/system.net.http.headers.headerstringvalues.enumerator.current?view=net-7.0&branch=pr-en-us-8336.

So I guess this PR is okay.

[carlossanlop]

But isn't there a bug with inheritdoc on operators specifically?

Ah, you're right. It's basically the same problem as the bug we opened: the parent API to inherit from is not found, so it's still considered undocumented, wrongly.

So I guess this PR is okay.

Thank you for checking. I'll merge.