-
Notifications
You must be signed in to change notification settings - Fork 5.1k
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
Conversation
@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. |
Co-authored-by: jeffhandley <[email protected]>
…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]>
There was a problem hiding this 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
There was a problem hiding this 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
.
...es/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingTraceSourceEventArgs.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLBinary.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
Outdated
Show resolved
Hide resolved
...es/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingTraceSourceEventArgs.cs
Outdated
Show resolved
Hide resolved
...aries/System.Configuration.ConfigurationManager/src/System/Diagnostics/TraceConfiguration.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLDecimal.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Data.Common/src/System/Data/SQLTypes/SQLMoney.cs
Outdated
Show resolved
Hide resolved
...braries/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingSwitchEventArgs.cs
Outdated
Show resolved
Hide resolved
...es/System.Diagnostics.TraceSource/src/System/Diagnostics/InitializingTraceSourceEventArgs.cs
Show resolved
Hide resolved
...es/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs
Outdated
Show resolved
Hide resolved
...es/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs
Outdated
Show resolved
Hide resolved
...es/System.Private.DataContractSerialization/src/System/Runtime/Serialization/DataContract.cs
Outdated
Show resolved
Hide resolved
…r XML doc tags Co-authored-by: tarekgh <[email protected]>
...s/System.Reflection.Metadata/src/System/Reflection/Metadata/Ecma335/Encoding/BlobEncoders.cs
Outdated
Show resolved
Hide resolved
There was a problem hiding this 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]>
…ers documentation Co-authored-by: tarekgh <[email protected]>
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. |
/ba-g failures include unrelated timeouts and known issues |
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 copyingSqlDecimal.WriteTdsValue(Span<uint>)
- Writes TDS representation to spanSqlMoney.FromTdsValue(long)
- Creates SqlMoney from TDS valueSqlMoney.GetTdsValue()
- Gets TDS representationSystem.Diagnostics (6/6 APIs)
InitializingSwitchEventArgs
constructor andSwitch
propertyInitializingTraceSourceEventArgs
constructor,TraceSource
andWasInitialized
propertiesTraceConfiguration
type documentationSystem.Reflection.Metadata.Ecma335 (1/1 API)
FieldTypeEncoder.CustomModifiers()
return value documentationSystem.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 constructorsX509SubjectAlternativeNameExtension.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:
<summary>
descriptions<param>
documentation for all parameters<returns>
documentation for return values<exception>
documentation where applicable<see>
tagsFiles 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.