Skip to content

Commit

Permalink
[bgen] Generate xml documentation for generated enums. (#20511)
Browse files Browse the repository at this point in the history 
This was mostly copied from the existing API documentation.

Partial fix for #20270.
  • Loading branch information
@rolfbjarne
rolfbjarne committed Apr 26, 2024
1 parent 0071fb3 commit 771453d
Show file tree
Hide file tree
Showing 10 changed files with 477 additions and 724 deletions.
28 changes: 28 additions & 0 deletions src/bgen/Enums.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,14 @@ void GenerateEnum (Type type)
var error = AttributeManager.GetCustomAttribute<ErrorDomainAttribute> (type);
if ((fields.Count > 0) || (error is not null) || (null_field is not null)) {
print ("");
if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Extension methods for the <see cref=\"global::{type.FullName}\" /> enumeration.</summary>");
if (error is not null) {
print ($"/// <remarks>");
print ($"/// <para>The extension method for the <see cref=\"global::{type.FullName}\" /> enumeration can be used to fetch the error domain associated with these error codes.</para>");
print ($"/// </remarks>");
}
}
// the *Extensions has the same version requirement as the enum itself
PrintPlatformAttributes (type);
print_generated_code ();
Expand All @@ -152,6 +160,13 @@ void GenerateEnum (Type type)
print ("[Field (\"{0}\", \"{1}\")]", error.ErrorDomain, library_name);
print ("static NSString? _domain;");
print ("");
if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Returns the error domain associated with the {type.FullName} value</summary>");
print ($"/// <param name=\"self\">The enumeration value</param>");
print ($"/// <remarks>");
print ($"/// <para>See the <see cref=\"global::Foundation.NSError\" /> for information on how to use the error domains when reporting errors.</para>");
print ($"/// </remarks>");
}
print ("public static NSString? GetDomain (this {0} self)", type.Name);
print ("{");
indent++;
Expand Down Expand Up @@ -197,6 +212,10 @@ void GenerateEnum (Type type)
print ("");
}

if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Retrieves the <see cref=\"global::Foundation.NSString\" /> constant that describes <paramref name=\"self\" />.</summary>");
print ($"/// <param name=\"self\">The instance on which this method operates.</param>");
}
print ("public static NSString? GetConstant (this {0} self)", type.Name);
print ("{");
indent++;
Expand Down Expand Up @@ -225,6 +244,10 @@ void GenerateEnum (Type type)
print ("");

var nullable = null_field is not null;
if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Retrieves the <see cref=\"global::{type.FullName}\" /> value named by <paramref name=\"constant\" />.</summary>");
print ($"/// <param name=\"constant\">The name of the constant to retrieve.</param>");
}
print ("public static {0} GetValue (NSString{1} constant)", type.Name, nullable ? "?" : "");
print ("{");
indent++;
Expand All @@ -251,6 +274,11 @@ void GenerateEnum (Type type)
print ("}");

if (isFlagsEnum) {
if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Retrieves all the <see cref=\"global::{type.FullName}\" /> constants named by the flags <paramref name=\"value\" />.</summary>");
print ($"/// <param name=\"value\">The flags to retrieve</param>");
print ($"/// <remarks>Any flags that are not recognized will be ignored.</remarks>");
}
print ($"public static NSString[] ToArray (this {type.Name} value)");
print ("{");
indent++;
Expand Down
724 changes: 0 additions & 724 deletions tests/cecil-tests/Documentation.KnownFailures.txt
View file

Large diffs are not rendered by default.

59 changes: 59 additions & 0 deletions tests/generator/ExpectedXmlDocs.MacCatalyst.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,65 @@
Summary for E1.Value1
</summary>
</member>
<member name="T:XmlDocumentation.E2">
<summary>
Summary for E2
</summary>
</member>
<member name="F:XmlDocumentation.E2.A">
<summary>
Summary for E2.A
</summary>
</member>
<member name="T:XmlDocumentation.E2Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E2" /> enumeration.</summary>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetConstant(XmlDocumentation.E2)">
<summary>Retrieves the <see cref="T:Foundation.NSString" /> constant that describes <paramref name="self" />.</summary>
<param name="self">The instance on which this method operates.</param>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetValue(Foundation.NSString)">
<summary>Retrieves the <see cref="T:XmlDocumentation.E2" /> value named by <paramref name="constant" />.</summary>
<param name="constant">The name of the constant to retrieve.</param>
</member>
<member name="T:XmlDocumentation.E3">
<summary>
Summary for E3
</summary>
</member>
<member name="F:XmlDocumentation.E3.ErrorA">
<summary>
Summary for E3.ErrorA
</summary>
</member>
<member name="T:XmlDocumentation.E3Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E3" /> enumeration.</summary>
<remarks>
<para>The extension method for the <see cref="T:XmlDocumentation.E3" /> enumeration can be used to fetch the error domain associated with these error codes.</para>
</remarks>
</member>
<member name="M:XmlDocumentation.E3Extensions.GetDomain(XmlDocumentation.E3)">
<summary>Returns the error domain associated with the XmlDocumentation.E3 value</summary>
<param name="self">The enumeration value</param>
<remarks>
<para>See the <see cref="T:Foundation.NSError" /> for information on how to use the error domains when reporting errors.</para>
</remarks>
</member>
<member name="T:XmlDocumentation.E4">
<summary>
Summary for E4
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit1">
<summary>
Summary for E4.Bit1
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit3">
<summary>
Summary for E4.Bit3
</summary>
</member>
<member name="T:XmlDocumentation.Notification1">
<summary>
Summary for Notification1
Expand Down
59 changes: 59 additions & 0 deletions tests/generator/ExpectedXmlDocs.iOS.legacy.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,65 @@
Summary for E1.Value1
</summary>
</member>
<member name="T:XmlDocumentation.E2">
<summary>
Summary for E2
</summary>
</member>
<member name="F:XmlDocumentation.E2.A">
<summary>
Summary for E2.A
</summary>
</member>
<member name="T:XmlDocumentation.E2Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E2" /> enumeration.</summary>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetConstant(XmlDocumentation.E2)">
<summary>Retrieves the <see cref="T:Foundation.NSString" /> constant that describes <paramref name="self" />.</summary>
<param name="self">The instance on which this method operates.</param>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetValue(Foundation.NSString)">
<summary>Retrieves the <see cref="T:XmlDocumentation.E2" /> value named by <paramref name="constant" />.</summary>
<param name="constant">The name of the constant to retrieve.</param>
</member>
<member name="T:XmlDocumentation.E3">
<summary>
Summary for E3
</summary>
</member>
<member name="F:XmlDocumentation.E3.ErrorA">
<summary>
Summary for E3.ErrorA
</summary>
</member>
<member name="T:XmlDocumentation.E3Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E3" /> enumeration.</summary>
<remarks>
<para>The extension method for the <see cref="T:XmlDocumentation.E3" /> enumeration can be used to fetch the error domain associated with these error codes.</para>
</remarks>
</member>
<member name="M:XmlDocumentation.E3Extensions.GetDomain(XmlDocumentation.E3)">
<summary>Returns the error domain associated with the XmlDocumentation.E3 value</summary>
<param name="self">The enumeration value</param>
<remarks>
<para>See the <see cref="T:Foundation.NSError" /> for information on how to use the error domains when reporting errors.</para>
</remarks>
</member>
<member name="T:XmlDocumentation.E4">
<summary>
Summary for E4
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit1">
<summary>
Summary for E4.Bit1
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit3">
<summary>
Summary for E4.Bit3
</summary>
</member>
<member name="T:XmlDocumentation.Notification1">
<summary>
Summary for Notification1
Expand Down
59 changes: 59 additions & 0 deletions tests/generator/ExpectedXmlDocs.iOS.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,65 @@
Summary for E1.Value1
</summary>
</member>
<member name="T:XmlDocumentation.E2">
<summary>
Summary for E2
</summary>
</member>
<member name="F:XmlDocumentation.E2.A">
<summary>
Summary for E2.A
</summary>
</member>
<member name="T:XmlDocumentation.E2Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E2" /> enumeration.</summary>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetConstant(XmlDocumentation.E2)">
<summary>Retrieves the <see cref="T:Foundation.NSString" /> constant that describes <paramref name="self" />.</summary>
<param name="self">The instance on which this method operates.</param>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetValue(Foundation.NSString)">
<summary>Retrieves the <see cref="T:XmlDocumentation.E2" /> value named by <paramref name="constant" />.</summary>
<param name="constant">The name of the constant to retrieve.</param>
</member>
<member name="T:XmlDocumentation.E3">
<summary>
Summary for E3
</summary>
</member>
<member name="F:XmlDocumentation.E3.ErrorA">
<summary>
Summary for E3.ErrorA
</summary>
</member>
<member name="T:XmlDocumentation.E3Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E3" /> enumeration.</summary>
<remarks>
<para>The extension method for the <see cref="T:XmlDocumentation.E3" /> enumeration can be used to fetch the error domain associated with these error codes.</para>
</remarks>
</member>
<member name="M:XmlDocumentation.E3Extensions.GetDomain(XmlDocumentation.E3)">
<summary>Returns the error domain associated with the XmlDocumentation.E3 value</summary>
<param name="self">The enumeration value</param>
<remarks>
<para>See the <see cref="T:Foundation.NSError" /> for information on how to use the error domains when reporting errors.</para>
</remarks>
</member>
<member name="T:XmlDocumentation.E4">
<summary>
Summary for E4
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit1">
<summary>
Summary for E4.Bit1
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit3">
<summary>
Summary for E4.Bit3
</summary>
</member>
<member name="T:XmlDocumentation.Notification1">
<summary>
Summary for Notification1
Expand Down
59 changes: 59 additions & 0 deletions tests/generator/ExpectedXmlDocs.macOS.legacy.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,65 @@
Summary for E1.Value1
</summary>
</member>
<member name="T:XmlDocumentation.E2">
<summary>
Summary for E2
</summary>
</member>
<member name="F:XmlDocumentation.E2.A">
<summary>
Summary for E2.A
</summary>
</member>
<member name="T:XmlDocumentation.E2Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E2" /> enumeration.</summary>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetConstant(XmlDocumentation.E2)">
<summary>Retrieves the <see cref="T:Foundation.NSString" /> constant that describes <paramref name="self" />.</summary>
<param name="self">The instance on which this method operates.</param>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetValue(Foundation.NSString)">
<summary>Retrieves the <see cref="T:XmlDocumentation.E2" /> value named by <paramref name="constant" />.</summary>
<param name="constant">The name of the constant to retrieve.</param>
</member>
<member name="T:XmlDocumentation.E3">
<summary>
Summary for E3
</summary>
</member>
<member name="F:XmlDocumentation.E3.ErrorA">
<summary>
Summary for E3.ErrorA
</summary>
</member>
<member name="T:XmlDocumentation.E3Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E3" /> enumeration.</summary>
<remarks>
<para>The extension method for the <see cref="T:XmlDocumentation.E3" /> enumeration can be used to fetch the error domain associated with these error codes.</para>
</remarks>
</member>
<member name="M:XmlDocumentation.E3Extensions.GetDomain(XmlDocumentation.E3)">
<summary>Returns the error domain associated with the XmlDocumentation.E3 value</summary>
<param name="self">The enumeration value</param>
<remarks>
<para>See the <see cref="T:Foundation.NSError" /> for information on how to use the error domains when reporting errors.</para>
</remarks>
</member>
<member name="T:XmlDocumentation.E4">
<summary>
Summary for E4
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit1">
<summary>
Summary for E4.Bit1
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit3">
<summary>
Summary for E4.Bit3
</summary>
</member>
<member name="T:XmlDocumentation.Notification1">
<summary>
Summary for Notification1
Expand Down
59 changes: 59 additions & 0 deletions tests/generator/ExpectedXmlDocs.macOS.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,65 @@
Summary for E1.Value1
</summary>
</member>
<member name="T:XmlDocumentation.E2">
<summary>
Summary for E2
</summary>
</member>
<member name="F:XmlDocumentation.E2.A">
<summary>
Summary for E2.A
</summary>
</member>
<member name="T:XmlDocumentation.E2Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E2" /> enumeration.</summary>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetConstant(XmlDocumentation.E2)">
<summary>Retrieves the <see cref="T:Foundation.NSString" /> constant that describes <paramref name="self" />.</summary>
<param name="self">The instance on which this method operates.</param>
</member>
<member name="M:XmlDocumentation.E2Extensions.GetValue(Foundation.NSString)">
<summary>Retrieves the <see cref="T:XmlDocumentation.E2" /> value named by <paramref name="constant" />.</summary>
<param name="constant">The name of the constant to retrieve.</param>
</member>
<member name="T:XmlDocumentation.E3">
<summary>
Summary for E3
</summary>
</member>
<member name="F:XmlDocumentation.E3.ErrorA">
<summary>
Summary for E3.ErrorA
</summary>
</member>
<member name="T:XmlDocumentation.E3Extensions">
<summary>Extension methods for the <see cref="T:XmlDocumentation.E3" /> enumeration.</summary>
<remarks>
<para>The extension method for the <see cref="T:XmlDocumentation.E3" /> enumeration can be used to fetch the error domain associated with these error codes.</para>
</remarks>
</member>
<member name="M:XmlDocumentation.E3Extensions.GetDomain(XmlDocumentation.E3)">
<summary>Returns the error domain associated with the XmlDocumentation.E3 value</summary>
<param name="self">The enumeration value</param>
<remarks>
<para>See the <see cref="T:Foundation.NSError" /> for information on how to use the error domains when reporting errors.</para>
</remarks>
</member>
<member name="T:XmlDocumentation.E4">
<summary>
Summary for E4
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit1">
<summary>
Summary for E4.Bit1
</summary>
</member>
<member name="F:XmlDocumentation.E4.Bit3">
<summary>
Summary for E4.Bit3
</summary>
</member>
<member name="T:XmlDocumentation.Notification1">
<summary>
Summary for Notification1
Expand Down
Loading

8 comments on commit 771453d

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

💻 [CI Build] Tests on macOS M1 - Mac Big Sur (11) passed 💻

✅ All tests on macOS M1 - Mac Big Sur (11) passed.

Pipeline on Agent
Hash: [CI build]

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

💻 [CI Build] Tests on macOS M1 - Mac Ventura (13) passed 💻

✅ All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent
Hash: [CI build]

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

💻 [CI Build] Tests on macOS M1 - Mac Monterey (12) passed 💻

✅ All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent
Hash: [CI build]

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

💻 [CI Build] Tests on macOS X64 - Mac Sonoma (14) passed 💻

✅ All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent
Hash: [CI build]

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

💻 [CI Build] Windows Integration Tests passed 💻

✅ All Windows Integration Tests passed.

Pipeline on Agent
Hash: 771453d8a40c9c18a1cb4f2caafc5c38cec49ca8 [CI build]

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

✅ API diff for current PR / commit

Legacy Xamarin (No breaking changes)
  • iOS (no change detected)
  • tvOS (no change detected)
  • watchOS (no change detected)
  • macOS (no change detected)
NET (empty diffs)
  • iOS: (empty diff detected)
  • tvOS: (empty diff detected)
  • MacCatalyst: (empty diff detected)
  • macOS: (empty diff detected)

✅ API diff vs stable

Legacy Xamarin (No breaking changes)
.NET (No breaking changes)
Legacy Xamarin (stable) vs .NET

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: 771453d8a40c9c18a1cb4f2caafc5c38cec49ca8 [CI build]

@vs-mobiletools-engineering-service2

This comment was marked as outdated.

Sign in to view

@vs-mobiletools-engineering-service2
Copy link
Collaborator

Choose a reason for hiding this comment

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

📚 [CI Build] Artifacts 📚

Packages generated

View packages

Pipeline on Agent
Hash: [CI build]

Please sign in to comment.