Skip to content
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.

Sign up for GitHub

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

[src] Ignore CS1573 in certain cases. #21941

Merged
merged 4 commits into from
Jan 13, 2025
Merged

[src] Ignore CS1573 in certain cases. #21941

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
84c225c
Add test
rolfbjarne Jan 10, 2025
e92be8c
[src] Ignore CS1573 in certain cases.
rolfbjarne Jan 10, 2025
ac7df93
Auto-format source code
Jan 10, 2025
6ff2721
Merge branch 'main' into dev/rolf/bgen-cs1573
mandel-macaque Jan 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion src/bgen/Generator.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4863,6 +4863,9 @@ void GenerateProtocolTypes (Type type, string class_visibility, string TypeName,
var extensionMethods = optionalInstanceMethods.Concat (requiredInstanceMethods.Where (v => IsRequired (v, out var generateExtensionMethod) && generateExtensionMethod));
var extensionProperties = optionalInstanceProperties.Concat (requiredInstanceProperties.Where (v => IsRequired (v, out var generateExtensionMethod) && generateExtensionMethod));

// disable CS1573, which can happen when the original member in the api definition has xml comments and we copy that xml comment into the generated interface - because we may add parameters to method signatures, and the new parameters won't have an xml comment.
print ("#pragma warning disable CS1573"); // Parameter 'This' has no matching param tag in the XML comment for '...' (but other parameters do)
Copy link
Contributor

Choose a reason for hiding this comment

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

Does it make sense to inject a comment as to why this is being disabled?

Copy link
Member Author

Choose a reason for hiding this comment

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

I don't think most people look at the code we generate, so probably not worth it.


WriteDocumentation (type);

PrintAttributes (type, platform: true, preserve: true, advice: true);
Expand Down Expand Up @@ -5153,12 +5156,16 @@ void GenerateProtocolTypes (Type type, string class_visibility, string TypeName,
print ("}");
print ("");

print ("#pragma warning restore CS1573");

// avoid (for unified) all the metadata for empty static classes, we can introduce them later when required
bool include_extensions = false;
if (backwardsCompatibleCodeGeneration)
include_extensions = extensionMethods.Any () || extensionProperties.Any () || requiredInstanceAsyncMethods.Any ();
if (include_extensions) {
// extension methods
// disable CS1573, which can happen when the original member in the api definition has xml comments and we copy that xml comment into the generated extension member - because we may add parameters to method signatures, and the new parameters won't have an xml comment.
print ("#pragma warning disable CS1573"); // Parameter 'This' has no matching param tag in the XML comment for '...' (but other parameters do)
// extension methods
if (BindingTouch.SupportsXmlDocumentation) {
print ($"/// <summary>Extension methods to the <see cref=\"I{TypeName}\" /> interface to support all the methods from the {protocol_name} protocol.</summary>");
print ($"/// <remarks>");
Expand Down Expand Up @@ -5199,6 +5206,7 @@ void GenerateProtocolTypes (Type type, string class_visibility, string TypeName,
indent--;
print ("}");
print ("");
print ("#pragma warning restore CS1573");
}

// Add API from base interfaces we also need to implement.
Expand Down
40 changes: 40 additions & 0 deletions tests/generator/ExpectedXmlDocs.MacCatalyst.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,26 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.IP1.PProperty">
<summary>
Summary for P1.PProperty
Expand All @@ -247,6 +267,16 @@
Summary for P1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.GetPProperty(XmlDocumentation.IP1)">
<summary>
Summary for P1.PProperty
Expand Down Expand Up @@ -356,6 +386,16 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.T1.PAProperty">
<summary>
Summary for PA1.PProperty
Expand Down
40 changes: 40 additions & 0 deletions tests/generator/ExpectedXmlDocs.iOS.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,26 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.IP1.PProperty">
<summary>
Summary for P1.PProperty
Expand All @@ -247,6 +267,16 @@
Summary for P1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.GetPProperty(XmlDocumentation.IP1)">
<summary>
Summary for P1.PProperty
Expand Down Expand Up @@ -356,6 +386,16 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.T1.PAProperty">
<summary>
Summary for PA1.PProperty
Expand Down
40 changes: 40 additions & 0 deletions tests/generator/ExpectedXmlDocs.macOS.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,26 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.IP1.PProperty">
<summary>
Summary for P1.PProperty
Expand All @@ -247,6 +267,16 @@
Summary for P1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.GetPProperty(XmlDocumentation.IP1)">
<summary>
Summary for P1.PProperty
Expand Down Expand Up @@ -356,6 +386,16 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.T1.PAProperty">
<summary>
Summary for PA1.PProperty
Expand Down
40 changes: 40 additions & 0 deletions tests/generator/ExpectedXmlDocs.tvOS.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -226,6 +226,26 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.IP1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.IP1._PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.IP1.PProperty">
<summary>
Summary for P1.PProperty
Expand All @@ -247,6 +267,16 @@
Summary for P1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.P1_Extensions.PMethodWithUndocumentedArgs(XmlDocumentation.IP1,System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="M:XmlDocumentation.P1_Extensions.GetPProperty(XmlDocumentation.IP1)">
<summary>
Summary for P1.PProperty
Expand Down Expand Up @@ -356,6 +386,16 @@
Summary for PA1.PMethod
</summary>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary><param name="arg0">Docs for arg0.</param>
</member>
<member name="M:XmlDocumentation.T1.PMethodWithUndocumentedArgs(System.Int32)">
<summary>
Summary for P1.PMethodWithArgs
</summary>
</member>
<member name="P:XmlDocumentation.T1.PAProperty">
<summary>
Summary for PA1.PProperty
Expand Down
14 changes: 14 additions & 0 deletions tests/generator/tests/xmldocs.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,20 @@ interface P1 {
[Abstract]
[Export ("propertyRequired")]
int PAProperty { get; set; }

/// <summary>
/// Summary for P1.PMethodWithArgs
/// </summary>
/// <param name="arg0">Docs for arg0.</param>
[Export ("method:")]
int PMethodWithArgs (int arg0);

/// <summary>
/// Summary for P1.PMethodWithArgs
/// </summary>
// No <param /> tag here
[Export ("methodWithUndocumentedArgs:")]
int PMethodWithUndocumentedArgs (int arg0);
}

/// <summary>
Expand Down
Loading