The C# targets emit no generated-file header, so consuming projects treat the output as hand-written source. The Python target already emits one, and both C# reference outputs begin directly with their using directives, core.cs with using Bonsai.Harp; and device.cs with using Bonsai;. Adding // <auto-generated/> as the first line would close that gap and has a measurable effect beyond tidiness.
Measured effect
Generating the core register interface with 0.7.0 and compiling it in a project with <Nullable>enable</Nullable> produces 22 warnings. Prefixing the emitted file with a single line takes that to zero, with no other change:
The warnings are genuine nullable-reference findings in the emitted PayloadMarshal helper, for example Buffer.BlockCopy and Array.Copy receiving segment.Array, which is nullable. They are correct observations about generated code that a consumer cannot act on, since the fix belongs in the template rather than in their project.
The effect is invisible to projects that leave nullable disabled, which is why this has not surfaced before. It appears the moment a consumer enables it.
What to emit
The machine-readable marker has to be the first line for the compiler to recognize the file as generated. The human-readable sentences the Python target already uses can follow, which keeps the two targets saying the same thing:
// <auto-generated/>
// This file was automatically generated and should not be edited directly.
// To make changes, edit the device metadata and regenerate the interface.
This applies to both C# outputs, since neither carries a header today.
Why it is worth doing beyond the warnings
It is the accurate statement about the file. It also keeps formatters and analyzer sweeps off generated output, so a repository running dotnet format or an unused-usings pass over its whole source tree does not rewrite a file that will be regenerated.
Drawbacks
Marking a file generated suppresses analyzer diagnostics inside it, so a genuine defect in emitted code stops being reported in consuming projects. That is the intended trade, since such a defect is the generator's to fix rather than the consumer's, but it does mean the templates carry the diagnostic burden and the reference outputs are where it has to be caught.
Implementation
The two C# reference outputs under tests/ExpectedOutput change by three lines each, which is the whole test impact.
The C# targets emit no generated-file header, so consuming projects treat the output as hand-written source. The Python target already emits one, and both C# reference outputs begin directly with their
usingdirectives,core.cswithusing Bonsai.Harp;anddevice.cswithusing Bonsai;. Adding// <auto-generated/>as the first line would close that gap and has a measurable effect beyond tidiness.Measured effect
Generating the core register interface with 0.7.0 and compiling it in a project with
<Nullable>enable</Nullable>produces 22 warnings. Prefixing the emitted file with a single line takes that to zero, with no other change:// <auto-generated/>The warnings are genuine nullable-reference findings in the emitted
PayloadMarshalhelper, for exampleBuffer.BlockCopyandArray.Copyreceivingsegment.Array, which is nullable. They are correct observations about generated code that a consumer cannot act on, since the fix belongs in the template rather than in their project.The effect is invisible to projects that leave nullable disabled, which is why this has not surfaced before. It appears the moment a consumer enables it.
What to emit
The machine-readable marker has to be the first line for the compiler to recognize the file as generated. The human-readable sentences the Python target already uses can follow, which keeps the two targets saying the same thing:
This applies to both C# outputs, since neither carries a header today.
Why it is worth doing beyond the warnings
It is the accurate statement about the file. It also keeps formatters and analyzer sweeps off generated output, so a repository running
dotnet formator an unused-usings pass over its whole source tree does not rewrite a file that will be regenerated.Drawbacks
Marking a file generated suppresses analyzer diagnostics inside it, so a genuine defect in emitted code stops being reported in consuming projects. That is the intended trade, since such a defect is the generator's to fix rather than the consumer's, but it does mean the templates carry the diagnostic burden and the reference outputs are where it has to be caught.
Implementation
The two C# reference outputs under
tests/ExpectedOutputchange by three lines each, which is the whole test impact.