search

eiriktsarpalis / PolyType

Practical generic programming for C#
https://eiriktsarpalis.github.io/PolyType/
MIT License
145 stars 6 forks source link

Suppress (or honor) CS1591 in generated code #35

Closed AArnott closed 2 weeks ago

AArnott commented 2 weeks ago

My project compiles with GenerateDocumentationFile set to true, so CS1591 flags all public APIs, even for generated code that uses // <auto-generated/>

2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.g.cs(15,31,15,38): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.Default'
2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.g.cs(17,16,17,23): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.Witness()'
2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.ITypeShapeProvider.g.cs(10,62,10,70): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.GetShape<T>()'
2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.ITypeShapeProvider.g.cs(13,59,13,67): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.GetShape(Type)'
2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.MessagePackSerializerTests_UnannotatedPoco.g.cs(13,110,13,152): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.MessagePackSerializerTests_UnannotatedPoco'
2>D:\source\Nerdbank.MessagePack\obj\test\Nerdbank.MessagePack.Tests\Debug\net8.0\TypeShape.SourceGenerator\TypeShape.SourceGenerator.TypeShapeIncrementalGenerator\MessagePackSerializerTests.Witness.Int32.g.cs(11,63,11,68): warning CS1591: Missing XML comment for publicly visible type or member 'MessagePackSerializerTests.Witness.Int32'

Can you either fully document the APIs you generate (which would be ideal) or use #pragma warning disable CS1591 at the top of your generated files to suppress these?

AArnott commented 2 weeks ago

Somehow this only seems to impact public witness classes. So at least it's a very justifiable workaround, since my witness class should typically not be public anyway.

eiriktsarpalis commented 2 weeks ago

Adding XML comments seems like a reasonable thing to do here.