Document new EditorConfig style rules

[cremor]

The following EditorConfig style rules supported in Visual Studio 2022 17.8 are currently not documented:

• dotnet_style_prefer_collection_expression
  Note: This setting affects both IDE0028 and IDE0300 (and maybe more). There is already a documentation for IDE0028 at https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/ide0028 but that page mentiones a different setting (dotnet_style_collection_initializer) which now seems to have no effect any more. This might be a bug.
• Experimental rules (see Should experimental IDExxxx be doc'ed? #23473):
  • dotnet_style_allow_statement_immediately_after_block_experimental
  • dotnet_style_allow_multiple_blank_lines_experimental
  • csharp_style_allow_blank_line_after_colon_in_constructor_initializer_experimental
  • csharp_style_allow_blank_lines_between_consecutive_braces_experimental
  • csharp_style_allow_embedded_statements_on_same_line_experimental
  • csharp_style_allow_blank_line_after_token_in_arrow_expression_clause_experimental
  • csharp_style_allow_blank_line_after_token_in_conditional_expression_experimental
• Maybe more, see comment below: Document new EditorConfig style rules #28791 (comment)

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: b0a396c1-9c21-75a9-70b5-799cafc941b5
• Version Independent ID: 6d91b560-c12f-6e6d-e92b-1babb27edb67
• Content: Code style rules overview - .NET
• Content Source: docs/fundamentals/code-analysis/style-rules/index.md
• Product: dotnet-fundamentals
• GitHub Login: @gewarren
• Microsoft Alias: gewarren

---

Associated WorkItem - 45471

[gewarren]

dotnet/roslyn#60546 says that IDE0161 (csharp_style_namespace_declarations) also needs to be documented.

Also, a helpful mapping of IDs to editorconfig options is here: https://github.com/dotnet/roslyn/blob/main/src/VisualStudio/Core/Def/CodeCleanup/readme.md

[cremor]

csharp_style_namespace_declarations is already documented here: https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/formatting-rules#namespace-options

But that page says "All formatting options have rule ID IDE0055 and title Fix formatting." If csharp_style_namespace_declarations is IDE0160/IDE0161, as mentioned in dotnet/roslyn#60546, then this section on that page would be wrong.

[Youssef1313]

dotnet/roslyn#60546 says that IDE0161 (csharp_style_namespace_declarations) also needs to be documented.

Also, a helpful mapping of IDs to editorconfig options is here: https://github.com/dotnet/roslyn/blob/main/src/VisualStudio/Core/Def/CodeCleanup/readme.md

FYI this list might get out of date very easily. Consider VisualBasic_VerifyIDECodeStyleOptionsAreConfigurable, CSharp_VerifyIDECodeStyleOptionsAreConfigurable tests here as a more reliable source

[Youssef1313]

I'm also planning to have a RulesMissingDocumentation.md in roslyn similar to roslyn-analyzers. But will take time to be able to get to it :(

[MisinformedDNA]

There's a good list of undocumented rules at https://github.com/madskristensen/EditorConfigLanguage/blob/master/src/Schema/EditorConfig.json

[cremor]

@MisinformedDNA Seems like this list is not fully up to date. Some of those settings are already documented (can be found with Google).

But thanks for the list anyway. There are some rules in there which I didn't know about. I only check the "Generate .editorconfig file from settings" feature of Visual Studio and the dotnet new editorconfig command for new rules (the last one is updated rarely/never?). Seems like there are rules which are unknown to both. Are those rules already considered finished? If not, there is no need to document them.

[Youssef1313]

I think we should wait on doc'ing experimental rules. The rest should be documented.

[alexrp]

Seems like there's a bunch of new ones here that should be documented: https://github.com/dotnet/roslyn/blob/35fda5cf56445624cb0837b8b9ddbd9aa8f98b95/src/Analyzers/Core/Analyzers/IDEDiagnosticIds.cs#L172-L182

There are some others in this range that I'm curious about too: https://github.com/dotnet/roslyn/blob/35fda5cf56445624cb0837b8b9ddbd9aa8f98b95/src/Analyzers/Core/Analyzers/IDEDiagnosticIds.cs#L185-L191 (e.g. IDE1007)

[Youssef1313]

@alexrp IDE1007 should not be documented, and (hopefully) will be removed soon.

[alexrp]

@Youssef1313 Fair enough. Just for posterity, can you clarify what its purpose is/was?

[Youssef1313]

@alexrp

Consider the following:

public class C
{
    public Test P { get; }
}

There is no type named Test defined, so the compiler produces:

error CS0246: The type or namespace name 'Test' could not be found (are you missing a using directive or an assembly reference?)

Some IDE features (e.g, generate type) are triggered by this compiler diagnostic:

https://github.com/dotnet/roslyn/blob/35fda5cf56445624cb0837b8b9ddbd9aa8f98b95/src/Features/CSharp/Portable/CodeFixes/GenerateType/GenerateTypeCodeFixProvider.cs#L41-L44

However, there are scenarios (incomplete members) where the compiler don't produce CS0246 (or similar) diagnostic.

So, for the following code:

public class C
{
    Test
}

The compiler only produces error CS1519: Invalid token '}' in class, record, struct, or interface member declaration. But we want the IDE to offer generate type for the above case. So, the IDE team implemented IDE1007 to fill this gap.

So, in short, IDE1007 is produced on already-error scenarios, but helps the IDE to trigger features such as generate type. It'll be removed when the compiler produces binding diagnostics that IDE1007 produces, which I'm working on in dotnet/roslyn#62874.

[cremor]

I've updated the issue description for Visual Studio 2022 17.3

[jknaudt21]

Hi, is there a known description on what the experimental rules do?

[cremor]

I've updated the issue description for Visual Studio 2022 17.4

@jknaudt21 I think the best "documentation" is the code preview in the VS options window.

[cremor]

I've updated the issue description for Visual Studio 2022 17.5.2

[cremor]

@gewarren Thanks for keeping this issue up-to-date for newly documented rules!
I've removed the done tasks from the issue description and added the new rule from Visual Studio 2022 17.7

[cremor]

@gewarren Thanks for keeping this issue up-to-date for newly documented rules!
I've removed the done tasks from the issue description and added the new rule from Visual Studio 2022 17.8

[cremor]

@gewarren It looks like everything (except experimental rules) from Visual Studio 2022 17.8 is now documented. Thanks!
I'd close this issue now. Or do you want me to keep it open and continue to report missing documentation for future VS releases here?

[gewarren]

Thanks @cremor. I'll close it now and we can open a new issue for future docs. Thanks for keeping this one up to date!