Add boilerplate documentation to generated types #30259
Conversation
…odeBehindGenerator Fixes dotnet#27911
There was a problem hiding this comment.
Pull Request Overview
This PR adds XML documentation boilerplate to code-behind classes and their default constructors generated by CodeBehindGenerator, preventing CS1591 warnings during documentation builds.
- Inserts
<summary>comments before the generated class and its XAML attribute. - Adds
<summary>comments for the optional default constructor. - Supports issue #27911 by ensuring documentation warnings are suppressed.
Comments suppressed due to low confidence (1)
src/Controls/src/SourceGen/CodeBehindGenerator.cs:307
- [nitpick] Consider referencing the generated class's CLR type name rather than the file path in the summary (e.g. 'Generated XAML code-behind for MainPage') to improve clarity for consumers.
sb.AppendLine($"\t/// Generated XAML code behind for {projItem.RelativePath}");
|
|
||
| sb.AppendLine($"namespace {rootClrNamespace}"); | ||
| sb.AppendLine("{"); | ||
| sb.AppendLine($"\t/// <summary>"); |
There was a problem hiding this comment.
Public docs live in XML under /docs/. Please update the relevant docs XML to describe the new boilerplate documentation feature so public documentation aligns with code changes.
Copilot uses AI. Check for mistakes.
| //optional default ctor | ||
| if (generateDefaultCtor) | ||
| { | ||
| sb.AppendLine($"\t\t/// <summary>"); |
There was a problem hiding this comment.
Ensure there are automated tests in TestCases.Shared.Tests and TestCases.HostApp that verify CodeBehindGenerator emits the expected <summary> comments for generated types and constructors.
Copilot uses AI. Check for mistakes.
| if (generateDefaultCtor) | ||
| { | ||
| sb.AppendLine($"\t\t/// <summary>"); | ||
| sb.AppendLine($"\t\t/// Creates a new {rootType}"); |
There was a problem hiding this comment.
This should follow the standard doc convention for constructors, otherwise anyone having standard doc enforced in their code analyzers would just generate warnings here.
| sb.AppendLine($"\t\t/// Creates a new {rootType}"); | |
| sb.AppendLine($"\t\t/// Initializes a new instance of the <see cref=\"{rootType}\" /> class."); |
| sb.AppendLine($"namespace {rootClrNamespace}"); | ||
| sb.AppendLine("{"); | ||
| sb.AppendLine($"\t/// <summary>"); | ||
| sb.AppendLine($"\t/// Generated XAML code behind for {projItem.RelativePath}"); |
There was a problem hiding this comment.
I don't think this is a great summary to end up in class documentation - those paths doesn't make sense in IntelliSense. Seems cleaner to just add a [GeneratedCode] attribute.
|
Hi @@mlorbetske. We have added the "s/pr-needs-author-input" label to this issue, which indicates that we have an open question/action for you before we can take further action. This PRwill be closed automatically in 14 days if we do not hear back from you by then - please feel free to re-open it if you come back to this PR after that time. |
|
Fixed with #30903, closing this one. Thanks for the effort! |
4 participants
Description of Change
Add boilerplate documentation to types and constructors produced by CodeBehindGenerator to prevent CS1591 from being raised on these members when documentation build is turned on.
Issues Fixed
Fixes #27911