Update messages for symbol comparison diagnostic and codefix

[ryzngard]

Fixes #3427

New messages:

Title: Symbols should be compared for equality
Message: Use 'SymbolEqualityComparer' when comparing symbols
Description: Symbols should be compared for equality, not identity. Use an overload accepting an 'IEqualityComparer' and pass 'SymbolEqualityComparer'.

[mavasani]

One or more auto-generated documentation files were either edited manually, or not updated. Please revert changes made to the following files (if manually edited) and run msbuild /t:pack for each solution at the root of the repo to automatically update them:
D:\workspace_work\1\s\src\Microsoft.CodeAnalysis.Analyzers\Microsoft.CodeAnalysis.Analyzers.md
D:\workspace_work\1\s\src\Microsoft.CodeAnalysis.Analyzers\Microsoft.CodeAnalysis.Analyzers.sarif
D:\workspace_work\1\s\src\Microsoft.CodeAnalysis.Analyzers\RulesMissingDocumentation.md

@ryzngard You need to run msbuild /t:pack at the root of the repo and push the changes.

[Youssef1313]

If I understand correctly, this is misleading. A code violating this rule is already comparing for equality. e,g symbolA.Equals(symbolB), and this is completely equivalent to symbolA.Equals(symbolB, SymbolEqualityComparer.Default).

The thing is mostly about the "intent" when there are nullable differences.

[Youssef1313]

The existing description (not touched in this PR) doesn't make much sense to me for the same reasoning in #5535 (comment).

[ryzngard]

Equality kind of stretches into inclusion/exclusion of nullable here. Shorthand to say "Should compare for equality" makes some sense to me, but I definitely see where the ", not identity" can be misleading.

[Youssef1313]

Equality kind of stretches into inclusion/exclusion of nullable here

That's exactly it. this is what should be indicated by the diagnostic.

Probably:

• Title: Make your symbol comparison intent explicit
• Message: Specify whether you want to include nullability when comparing symbols
• Description: When comparing symbols, explicitly specify a 'SymbolEqualityComparer' to indicate whether you want to include nullability in comparison

(I know my wording isn't very good, but something along those lines?)

[ryzngard]

What about:

• Title: Symbol comparison should use 'SymbolEqualityComparer'
• Message: Use a 'SymbolEqualityComparer' to specify whether to include nullability when comparing symbols
• Description: When comparing symbols, it's good practice to specify whether symbols with different nullability should be considered equal. Use a 'SymbolEqualityComparer' to specify in this comparison whether to include nullability as part of the equality check.

[ryzngard]

That way the title tells you what we expect, the message and description both elaborate on the why

[Youssef1313]

Much better!

[ryzngard]

Thanks for the feedback :) I'll see if I can get that in this afternoon