Improve Documentation Around // <auto-generated/>

[aolszowka]

We have a third party source file that we are using (NDesk.Options) which has its own code style. We do not want to apply any formatting to this file. Instead we want to exclude this from analysis/formatting.

As per DotNetAnalyzers/StyleCopAnalyzers#2960 (comment)

The way to work around this is to put this at the top of the file:

// <auto-generated/>

However testing dotnet-format has shown that this MUST be the first line of the file, where as Visual Studio/Roslyn Analyzers appear to be a bit more forgiving (it looks like so long as it is part of the first comment block it works).

This should probably be documented somewhere if this is intended.

C:\GitHub\VisualStudioSolutionUpdater>dotnet format --version
5.0.152601+7d7b7f05e9ed67cc4c983b9164add3eb32fa6518

FWIW the .editorconfig suggestion also works as documented by Sam and should probably be called out as well.

[sharwell]

However testing dotnet-format has shown that this MUST be the first line of the file

This is a bug in dotnet-format

[JoeRobich]

However testing dotnet-format has shown that this MUST be the first line of the file

@aolszowka Sorry you are running into issues. Can you provide a repro? I added a test for this scenario and it seems to be working.

[aolszowka]

Ugh I am SO SORRY, I cannot get this to repro either, I suspect, but cannot prove this was a PEBAK Error on my part, I have a really bad habit of misspelling generate (usually as genarate or something along those lines).

Again SO SORRY To sound the alarm on this and waste everyone's time :(

It would still be worth it I think to call this out somewhere in the documentation, maybe I just missed it but yeah totally MY FAULT. I will try to have a repro next time before opening an issue :( Please feel free to close this.

[sharwell]

@aolszowka no problem, I know I do the same thing often

[JoeRobich]

@aolszowka No worries. I agree that we should have documentation for this scenario. We also support the generated_code editorconfig settings described in https://docs.microsoft.com/en-us/visualstudio/code-quality/use-roslyn-analyzers?view=vs-2019#configure-generated-code