WindowsAppSDK-VersionInfo.cs and MddBootstrapAutoInitializer.cs cause warnings in analyzers

[Balkoth]

Describe the bug

Setting <GenerateDocumentationFile>True</GenerateDocumentationFile> in the project causes the following warnings to appear:

Another issue is reported here:
DotNetAnalyzers/StyleCopAnalyzers/#3441

Steps to reproduce the bug

1.) Create a new WinUI 3 app with the template: Blank App, Packaged (WinUI 3 in Desktop)
2.) Enable documentation generation
3.) Build the app

Expected behavior

Warnings from nuget packages should not appear in any project that uses them.

Screenshots

No response

NuGet package version

1.0.0

Packaging type

Packaged (MSIX), Unpackaged

Windows version

Windows 10 version 2004 (19041, May 2020 Update)

IDE

Visual Studio 2022

Additional context

No response

[Balkoth]

This bug still exists in v1.0.1

[Donsroom]

In version 1.1.0-preview2 I don't get warnings but I do get several messages. I think this is caused by me having many of my VS code style settings set to "Suggestion" instead of "Refactoring Only". Is there a way to exclude this file from being checked against the VS code style settings (ie. Tools | options | Text Editor | C# | Code Style)

[Balkoth]

Still not fixed in v1.1.0

[mattleibow]

Should these classes be internal?

[evelynwu-msft]

@DrusTheAxe It appears that there are additional StyleCop warnings that aren't covered by #2533; is that expected?

[Balkoth]

Still not fixed in v1.1.2

[DrusTheAxe]

I'll be looking at it next week

[Balkoth]

Still not fixed in v1.1.3

[DrusTheAxe]

I did some digging...

Workaround here => dotnet/roslyn#53729 (comment)

Official word is it's a feature => dotnet/roslyn#53729 (comment)

Closing because this behavior is "By Design" and I don't really see us changing it here. The compiler itself has very little understanding of generated code in terms of how it handles diagnostics. That is true for the types of files that we register as generated as well as the behavior we tweak for those files (think it's pretty much just nullable diagnostics at this point).

The solution here is to either generate the correct code or to disable the warning in editorconfig for that pattern of files (as you showed in the sample above)

Another discussion with the full menu of options => https://stackoverflow.com/questions/7982525/visual-studio-disabling-missing-xml-comment-warning

To summarise, the ways around the warning would be to:

• Suppress the warning by changing the project Properties > Build > Errors and warnings > Suppress warnings by entering 1591
• Add the XML documentation tags (GhostDoc can be quite handy for that)
• Suppress the warning via compiler options
  Uncheck the "XML documentation file" checkbox in project Properties > Build > Output
• Add #pragma warning disable 1591 at the top of the respective file and #pragma warning restore 1591 at the bottom

and a little later in that thread a C# specific answer which looks most promising

You can also modify your project's .csproj file to include a 1591 tag inside of the first . Originally from Alexandru Bucur's Article Here

... 1591 ...

@DefaultRyan is it possible to declare that <PropertyGroup> in one of our nuget's .props to address this?

[Balkoth]

How about you just document the stuff...

[DrusTheAxe]

We do e.g. https://docs.microsoft.com/en-us/windows/apps/api-reference/cs-bootstrapper-apis/cs-bootstrapper-apis-constants.

This isn't about documenting our stuff, but a matter of how, or more precisely, where.

Is it just the warning noise that's an issue?

Does having doccomments in source bring any additional value (or issues)?

Just for files like MddBootstrapAutoInitialize.cs that are compiled into your binaries or others as well e.g. WinAPI APIs available to C# developers via C#/WinRT like `Microsoft.Windows.ApplicationModel.DynamicDependency'?

[Balkoth]

Imho it is noise. Noise that should not be there as i as developer have no control over those files. I should not have to do anything to work around those warnings.

[DrusTheAxe]

Imho it is noise.

Gotcha. Thanks for the input.

I should not have to do anything to work around those warnings.

No disagreement, just trying to figure out the needs and best ways to squash the issue. I have a simple fix for the surface issue and we're discussing if a bigger change is warranted for the larger picture. I've teed up a patch for main and will bring it for 1.1-servicing consideration for our next servicing update.

[MartyIX]

Developing .NET MAUI app with .NET 7.0, I can still see some warnings from WindowsAppSDK-VersionInfo.cs from time to time. Is it just me or can you see it too?

[symbiogenesis]

I can see it too, also on MAUI.

This file really needs to start with:

/// <auto-generated>

Also, I'm not sure, but I suspect that it is related to setting the property GenerateDocumentationFile to true, and could likely be fixed by setting it to false. Setting it to true probably isn't really necessary unless you are building a library for public consumption.

But this is clearly a bug.

[DrusTheAxe]

WindowsAppSDK-VersionInfo.cs was missed in the pass previously fixing this. in other files.

That's generated out of another repo so I'll cook a fix over there. Thanks for reporting this.

[symbiogenesis]

I'm still seeing this. Maybe because <auto-generated> isn't on the very first line?

Tagging it with the GeneratedCodeAttribute may also fix it

[MartyIX]

Not fixed for me as well.