ResxSourceGenerator: Added XML comment summary to the generated classes and properties to avoid warning CS1591 if they are public

[uo1]

If the classes generated by the ResxSourceGenerator are public, the warning CS1591 has been emitted, since the XML comments were missing.

Fixes #7478

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.50%. Comparing base (7f449a5) to head (5cae283).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #7366   +/-   ##
=======================================
  Coverage   96.50%   96.50%           
=======================================
  Files        1450     1450           
  Lines      347435   347455   +20     
  Branches    11413    11413           
=======================================
+ Hits       335297   335317   +20     
- Misses       9245     9246    +1     
+ Partials     2893     2892    -1     

[uo1]

Duplicate was created in pull request #7479.

[uo1]

Closes issue #7478.

[sharwell]

I would generally prefer to not make this change in the current form, since the comments here aren't particularly helpful. I would expect the comments here to be derived from one of the following:

1. Locate one or more similar types in the BCL / .NET SDK, and model the documentation after the standard form used for those types/members.
2. If no similar types can be found, the wording should be modeled after the closest types/members with similar usage characteristics.

I generally recommend disabling CS1591 among a couple others, although this strategy won't work for all users:

roslyn-analyzers/Directory.Build.props

Lines 37 to 45 in 5435ba7

	<!--
	Make sure any documentation comments which are included in code get checked for syntax during the build, but do
	not report warnings for missing comments.
	CS1573: Parameter 'parameter' has no matching param tag in the XML comment for 'member' (but other parameters do)
	CS1591: Missing XML comment for publicly visible type or member 'Type_or_Member'
	CS1712: Type parameter 'parameter' has no matching typeparam tag in the XML comment on 'type_or_member' (but other type parameters do)
	-->
	<NoWarn Condition="'$(Language)' == 'C#'">$(NoWarn),1573,1591,1712</NoWarn>

[dvoituron]

I generally recommend disabling CS1591 among a couple others, although this strategy won't work for all users:

Indeed, when you activate the CS1591 requirement in your project, it cannot be deactivated for auto-generated files.
This is probably because they are generated in a folder other than the project folder.

[uo1]

I generally recommend disabling CS1591 among a couple others, although this strategy won't work for all users:

Indeed, when you activate the CS1591 requirement in your project, it cannot be deactivated for auto-generated files. This is probably because they are generated in a folder other than the project folder.

If there is a straightforward way to disable CS1591 for generated code, created from source code generators, it would be great. But unfortunately, it seems there isn't, at least not yet. There is only a quite hacky work around.

Generate the resource classes as internal is not always a solution either, e.g. because of the issue dotnet/runtime/issues/110073.

But of course, making the XML comment more descriptive is a legit point.

[uo1]

I would generally prefer to not make this change in the current form, since the comments here aren't particularly helpful. I would expect the comments here to be derived from one of the following:

1. Locate one or more similar types in the BCL / .NET SDK, and model the documentation after the standard form used for those types/members.
2. If no similar types can be found, the wording should be modeled after the closest types/members with similar usage characteristics.

@sharwell I updated the pull request with more descriptive XML comments, which I took from the classic ResXFileCodeGenerator.