Improve Documentation Around `// <auto-generated/>`

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 https://github.com/DotNetAnalyzers/StyleCopAnalyzers/issues/2960#issuecomment-642851675

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]

@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