Port inheritdoc tag for runtime APIs that are missing docs

[carlossanlop]

MS Docs is smart enough to automatically show inherited documentation if the <inheritdoc/> tag is present. If an API contains such tag in the intellisense xml, we can port that tag instead of copying the parent's documentation directly. But if the API contains documentation (partial or total) in the intellisense xml, we want to port that, because we should assume the owner wants to override some or all of the parent's documentation.

The docs porting tool is now able to port documentation following that logic.

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.

I submitted another PR #8336 that includes the rest of the inheritdoc tags that were detected in APIs that have already been fully documented before (by copying the base type or the interface's documentation).

[carlossanlop]

@dotnet/area-extensions-configuration @dotnet/area-extensions-dependencyinjection @dotnet/area-extensions-logging @dotnet/area-extensions-primitives @dotnet/area-system-componentmodel @dotnet/ncl @dotnet/area-system-numerics @dotnet/interop-contrib @dotnet/area-system-security @dotnet/area-system-runtime @dotnet/area-system-globalization @tarekgh @jozkee

[BillWagner]

Hi @carlossanlop

Once the remaining conversations are resolved, this LGTM.

[carlossanlop]

Only one more thing to address: the warnings and suggestions. Most, if not all, showed up due to the unexpected escaping of characters.

[carlossanlop]

Trying some fixes for the CI suggestions.

[opbld31]

Docs Build status updates of commit 95da900:

✅ Validation status: passed

File	Status	Preview URL	Details
xml/Microsoft.Extensions.Primitives/StringValues.xml	💡Suggestion	View	Details
xml/System.Numerics/BigInteger.xml	💡Suggestion	View	Details
xml/System.Numerics/Complex.xml	💡Suggestion	View	Details
xml/System.Security.Cryptography.Cose/CoseHeaderMap.xml	💡Suggestion	View	Details
xml/System/DateTime.xml	💡Suggestion	View	Details
xml/System/DateTimeOffset.xml	💡Suggestion	View	Details
xml/System/Decimal.xml	💡Suggestion	View	Details
xml/System/Double.xml	💡Suggestion	View	Details
xml/System/Guid.xml	💡Suggestion	View	Details
xml/System/Half.xml	💡Suggestion	View	Details
xml/System/Int128.xml	💡Suggestion	View	Details
xml/System/Single.xml	💡Suggestion	View	Details
xml/System/UInt128.xml	💡Suggestion	View	Details
xml/Microsoft.Extensions.Configuration/ConfigurationManager.xml	✅Succeeded	View
xml/Microsoft.Extensions.DependencyInjection/AsyncServiceScope.xml	✅Succeeded	View
xml/Microsoft.Extensions.DependencyInjection/ServiceCollection.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Abstractions/NullLogger.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Abstractions/NullLogger`1.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Abstractions/NullLoggerFactory.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Console/ConsoleLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Debug/DebugLogger.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.Debug/DebugLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.EventLog/EventLogLogger.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging.EventLog/EventLogLoggerProvider.xml	✅Succeeded	View
xml/Microsoft.Extensions.Logging/Logger`1.xml	✅Succeeded	View

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

xml/Microsoft.Extensions.Primitives/StringValues.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:Microsoft.Extensions.Primitives.StringValues.op_Equality(System.String[],Microsoft.Extensions.Primitives.StringValues).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:Microsoft.Extensions.Primitives.StringValues.op_Equality(Microsoft.Extensions.Primitives.StringValues,System.String[]).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:Microsoft.Extensions.Primitives.StringValues.op_Equality(System.String,Microsoft.Extensions.Primitives.StringValues).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:Microsoft.Extensions.Primitives.StringValues.op_Equality(Microsoft.Extensions.Primitives.StringValues,System.String).

xml/System.Numerics/BigInteger.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Numerics.BigInteger.op_UnsignedRightShift(System.Numerics.BigInteger,System.Int32).

xml/System.Numerics/Complex.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Numerics.Complex.op_Decrement(System.Numerics.Complex).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Numerics.Complex.op_Increment(System.Numerics.Complex).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Numerics.Complex.op_UnaryPlus(System.Numerics.Complex).

xml/System.Security.Cryptography.Cose/CoseHeaderMap.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:Contains(System.Collections.Generic.KeyValuePair{System.Security.Cryptography.Cose.CoseHeaderLabel,System.Security.Cryptography.Cose.CoseHeaderValue}) for uid: System.Security.Cryptography.Cose.CoseHeaderMap.Contains(System.Collections.Generic.KeyValuePair{System.Security.Cryptography.Cose.CoseHeaderLabel,System.Security.Cryptography.Cose.CoseHeaderValue}).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundParent] Found no member can be inherited by key:TryGetValue(System.Security.Cryptography.Cose.CoseHeaderLabel,System.Security.Cryptography.Cose.CoseHeaderValue@) for uid: System.Security.Cryptography.Cose.CoseHeaderMap.TryGetValue(System.Security.Cryptography.Cose.CoseHeaderLabel,System.Security.Cryptography.Cose.CoseHeaderValue@).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NoFoundDocs] Inheridoc tag exists but no inheritdoc found for uid:System.Security.Cryptography.Cose.CoseHeaderMap.TryGetValue(System.Security.Cryptography.Cose.CoseHeaderLabel,System.Security.Cryptography.Cose.CoseHeaderValue@).

xml/System/DateTime.xml

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

xml/System/DateTimeOffset.xml

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

xml/System/Decimal.xml

• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_Decrement(System.Decimal).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_Division(System.Decimal,System.Decimal).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_Equality(System.Decimal,System.Decimal).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_GreaterThan(System.Decimal,System.Decimal).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_GreaterThanOrEqual(System.Decimal,System.Decimal).
• Line 0, Column 0: [Suggestion: ECMA2Yaml_Inheritdoc_NotSupportType] Inheridoc not support type: Operator for uid:System.Decimal.op_Increment(System.Decimal).

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

[carlossanlop]

@gewarren I have high suspicion that the suggestions are mdoc bugs. I'll merge this PR but we can discuss the error messages separately in case we need to act on them. I mainly need the undoc APIs report to show these as documented.