Skip to content

Add XML documentation for 29 undocumented .NET 7.0 APIs #117697

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Jul 26, 2025

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jul 16, 2025

This PR adds comprehensive XML documentation for 29 undocumented APIs across 7 major namespaces in the .NET 7.0 runtime, addressing part of the documentation gap identified in issue #76049.

APIs Documented

System.Data.SqlTypes (4/4 APIs)

  • SqlBinary.WrapBytes(byte[]) - Wraps a byte array without copying
  • SqlDecimal.WriteTdsValue(Span<uint>) - Writes TDS representation to span
  • SqlMoney.FromTdsValue(long) - Creates SqlMoney from TDS value
  • SqlMoney.GetTdsValue() - Gets TDS representation

System.Diagnostics (6/6 APIs)

  • InitializingSwitchEventArgs constructor and Switch property
  • InitializingTraceSourceEventArgs constructor, TraceSource and WasInitialized properties
  • TraceConfiguration type documentation

System.Reflection.Metadata.Ecma335 (1/1 API)

  • FieldTypeEncoder.CustomModifiers() return value documentation

System.Runtime.Serialization.Json (2/2 APIs)

  • DataContractJsonSerializer.GetSerializationSurrogateProvider()
  • DataContractJsonSerializer.SetSerializationSurrogateProvider(ISerializationSurrogateProvider)

System.Runtime.Versioning (4/4 APIs)

  • ObsoletedOSPlatformAttribute constructors and properties (Message, Url)

System.Security.Cryptography (7 APIs)

  • X509SubjectAlternativeNameExtension type and constructors
  • X509SubjectAlternativeNameExtension.CopyFrom(AsnEncodedData)
  • X509SubjectAlternativeNameExtension.EnumerateDnsNames()
  • X509SubjectAlternativeNameExtension.EnumerateIPAddresses()

System.Runtime.Serialization.DataContracts (5 APIs)

  • DataContract type and core properties (ContractType, IsValueType, IsReference, XmlName, BaseContract)

Documentation Standards

All documentation follows established .NET XML documentation conventions:

  • Comprehensive <summary> descriptions
  • Detailed <param> documentation for all parameters
  • <returns> documentation for return values
  • <exception> documentation where applicable
  • Proper cross-references using <see> tags

Files Modified

  • src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLBinary.cs
  • src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
  • src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
  • src/libraries/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingSwitchEventArgs.cs
  • src/libraries/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingTraceSourceEventArgs.cs
  • src/libraries/System.Configuration.ConfigurationManager/src/System/Diagnostics/TraceConfiguration.cs
  • src/libraries/System.Reflection.Metadata/src/System/Reflection/Metadata/Ecma335/Encoding/BlobEncoders.cs
  • src/libraries/System.Private.CoreLib/src/System/Runtime/Versioning/PlatformAttributes.cs
  • src/libraries/System.Private.DataContractSerialization/src/System/Runtime/Serialization/Json/DataContractJsonSerializer.cs
  • src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/X509Certificates/X509SubjectAlternativeNameExtension.cs
  • src/libraries/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs

This work provides a foundation of high-quality API documentation that can serve as a template for documenting the remaining APIs in the original issue.

Addressing #76049.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

@jeffhandley
Copy link
Member

@copilot Please note that according to the comment at #76049 (comment), some of the originally reported APIs were no longer missing XML docs. It's possible others have had docs added since that comment as well.

Copilot AI and others added 3 commits July 16, 2025 07:13
…ioning, System.Security.Cryptography.Cose and System.Runtime.Serialization.Json APIs

Co-authored-by: jeffhandley <[email protected]>
…509SubjectAlternativeNameExtension and System.Runtime.Serialization.DataContracts.DataContract APIs

Co-authored-by: jeffhandley <[email protected]>
@Copilot Copilot AI changed the title [WIP] Undocumented 7.0 APIs as of RC2 Add XML documentation for 29 undocumented .NET 7.0 APIs Jul 16, 2025
Copilot finished work on behalf of jeffhandley July 16, 2025 07:26
@Copilot Copilot AI requested a review from jeffhandley July 16, 2025 07:26
Copy link
Member

@jeffhandley jeffhandley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use tags throughout when referencing APIs, and tags for C# language keywords.

More documentation on recommended tags can be found at: https://learn.microsoft.com/dotnet/csharp/language-reference/xmldoc/recommended-tags

Copy link
Member

@jeffhandley jeffhandley left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use <see cref="{API}" /> when referencing API names. Use <see langword="{langword}" /> for C# language keywords such as null.

Copilot finished work on behalf of tarekgh July 22, 2025 15:35
@Copilot Copilot AI requested a review from tarekgh July 22, 2025 15:35
Copy link
Member

@tarekgh tarekgh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added some suggestions, LGTM otherwise.

…and restore X509SubjectAlternativeNameExtension docs

Co-authored-by: tarekgh <[email protected]>
Copilot finished work on behalf of tarekgh July 22, 2025 16:08
@Copilot Copilot AI requested a review from tarekgh July 22, 2025 16:08
Copy link
Contributor Author

Copilot AI commented Jul 22, 2025

@copilot Please note that according to the comment at #76049 (comment), some of the originally reported APIs were no longer missing XML docs. It's...

You're absolutely right. The documentation landscape has changed since the original issue was created in 2022. Some APIs listed in the original issue may have been documented in subsequent updates. This PR focuses on APIs that were confirmed to be missing documentation in the current source code. In future documentation efforts, I'll be sure to verify the current state of documentation before starting work.

@jeffhandley
Copy link
Member

/ba-g failures include unrelated timeouts and known issues

@jeffhandley jeffhandley merged commit a2b08f1 into main Jul 26, 2025
137 of 143 checks passed
@jeffhandley jeffhandley deleted the copilot/fix-76049 branch July 26, 2025 11:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants