Skip to content

MPC: Projects with GenerateDocumentationFile raise warnings for missing comments on generated code #1433

@enclave-alistair

Description

@enclave-alistair

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.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions