Is your feature request related to a problem? Please describe.
We are using the MessagePack.MSBuild.Tasks package to generate formatters and resolvers at build time, in a library released via NuGet. This library has <GenerateDocumentationFile>true</GenerateDocumentationFile> in the csproj, meaning that all public surface that is missing appropriate comments yields the CS1591 compiler warning. None of the MPC templates have comments so we get a bunch of errors, e.g.
.\obj\Debug\net6.0\mpc_generated.cs(1019,25,1019,52): warning CS1591: Missing XML comment for publicly visible type or member 'MyTypeFormatter'
.\obj\Debug\net6.0\mpc_generated.cs(960,21,960,30): warning CS1591: Missing XML comment for publicly visible type or member 'MyTypeFormatter.Serialize(ref MessagePackWriter, MyType, MessagePackSerializerOptions)'
It is unfortunately not possible to suppress CS1591 just for mpc_generated.cs, and with a lot of formatters to generate, these warnings cause a lot of noise in our build process; as a general rule we go for zero-warnings on all builds. If someone has TreatWarningsAsErrors switched on, this would become much more painful.
Describe the solution you'd like
The simplest solution that works is to add #pragma warning disable 1591 to the templates in MessagePack.GeneratorCore. This achieves the desired goal.
Describe alternatives you've considered
- You could provide an option to make all the formatters
internal visibility, leaving the resolver public. Then document the generated resolver code. This is arguably a better fix, but is more complicated.
- Fully document everything in the templates; too much work, and would have to be kept up to date with the rest of the codebase.
Additional context
I'm able to submit a PR with this change, once agreed.
Is your feature request related to a problem? Please describe.
We are using the
MessagePack.MSBuild.Taskspackage to generate formatters and resolvers at build time, in a library released via NuGet. This library has<GenerateDocumentationFile>true</GenerateDocumentationFile>in the csproj, meaning that all public surface that is missing appropriate comments yields theCS1591compiler warning. None of the MPC templates have comments so we get a bunch of errors, e.g.It is unfortunately not possible to suppress
CS1591just formpc_generated.cs, and with a lot of formatters to generate, these warnings cause a lot of noise in our build process; as a general rule we go for zero-warnings on all builds. If someone hasTreatWarningsAsErrorsswitched on, this would become much more painful.Describe the solution you'd like
The simplest solution that works is to add
#pragma warning disable 1591to the templates inMessagePack.GeneratorCore. This achieves the desired goal.Describe alternatives you've considered
internalvisibility, leaving the resolverpublic. Then document the generated resolver code. This is arguably a better fix, but is more complicated.Additional context
I'm able to submit a PR with this change, once agreed.