dotnet / dotnet/msbuild

CS warnings appear in Resources.Designer.cs when a resource file excerpt line starts with `/`

Open
#6,677 8 comments 0 reactions 0 assignees View on GitHub
bug triaged
Dominant language
C#
Stars
5.5k
Forks
1.5k
Avg merge
1d 8h
Merged PRs (30d)
141

Description

Due to a bug in CodeDom's generation of C# code comments that the StronglyTypedResourceBuilder class in this repo does nothing to avoid, any project with `true` that embeds a file that contains a line that starts with `/` gets invalid C# documentation syntax in .Designer.cs, resulting in warnings:

![image](https://user-images.githubusercontent.com/8040367/119894744-fb340280-bf0a-11eb-99a1-0cfdd46f18a7.png)

I asked first at https://github.com/dotnet/roslyn/issues/53729 in case the compiler team thought that documentation warnings should be skipped in generated code, and they decided that the current behavior is by design.

### Steps to Reproduce

Full repro: [Repro.zip](https://github.com/dotnet/roslyn/files/6556702/Repro.zip)

Resource file being included (real-life example was a SQL file that was truncated by the resource code generator when included in the XML comment):

```

/
```

Problematic excerpt from Resources.Designer.cs:

```cs
///
/// Looks up a localized string similar to
////.
///
internal static string SomeResourceFile {
get {
return ResourceManager.GetString("SomeResourceFile", resourceCulture);
}
}
```

Project file:

```xml


net5.0
true



True
True
Resources.resx



ResXFileCodeGenerator
Resources.Designer.cs

```

Specific errors:

![image](https://user-images.githubusercontent.com/8040367/119894927-39c9bd00-bf0b-11eb-818a-fb195ef813a9.png)

![image](https://user-images.githubusercontent.com/8040367/119894894-2f0f2800-bf0b-11eb-8bc9-62701c664b2c.png)

![image](https://user-images.githubusercontent.com/8040367/119894847-1bfc5800-bf0b-11eb-83ea-2fbf378d4f39.png)

### Analysis

This is where CodeDom creates the invalid `////` XML doc comment line: https://github.com/dotnet/runtime/blob/v5.0.6/src/libraries/System.CodeDom/src/Microsoft/CSharp/CSharpCodeGenerator.cs#L879
.NET Framework's CodeDom has the same bug: https://referencesource.microsoft.com/#System/compmod/microsoft/csharp/csharpcodeprovider.cs,e0b125d92a26ca23

On that line it outputs `///` because of `string commentLineStart = e.DocComment ? "///" : "//";` outside that loop. Then the next character of `value` that will be written after that is a single `/`. This causes invalid C# any time a forward slash follows a newline in `CodeComment.Text`.

There does not appear to be a way to work around this by instructing the Resources.Designer.cs generator to stop putting file content in XML comments: https://github.com/dotnet/msbuild/blob/v16.10.0/src/Tasks/system.design/stronglytypedresourcebuilder.cs#L562-L593

A workaround is to put this in .editorconfig:

```ini
[*.Designer.cs] # Workaround for https://github.com/dotnet/roslyn/issues/53729
dotnet_diagnostic.CS1570.severity = none
dotnet_diagnostic.CS1587.severity = none
```

### Versions & Configurations

Visual Studio 16.10.0

This also afflicts the StronglyTypedResourceBuilder in .NET Framework's Microsoft.Build.Tasks.v4.0.dll assembly, file version 4.8.4084.0.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.