Skip to content

Commit

Permalink
Merge pull request #722 from JoeRobich/update-docs
Browse files Browse the repository at this point in the history 
Update documentation for analyzers
  • Loading branch information
@JoeRobich
JoeRobich committed Jul 6, 2020
2 parents 4af06ea + 5d9254b commit bc6d17b
Show file tree
Hide file tree
Showing 20 changed files with 208 additions and 202 deletions.
37 changes: 22 additions & 15 deletions README.md
View file
Expand Up @@ -7,12 +7,13 @@

|Branch| Windows (Debug)| Windows (Release)| Linux (Debug) | Linux (Release) | Localization (Debug) | Localization (Release) |
|---|:--:|:--:|:--:|:--:|:--:|:--:|
[master](https://github.com/dotnet/format/tree/master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows&configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows&configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Linux&configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Linux&configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows_Spanish&configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows_Spanish&configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|
[master](https://github.com/dotnet/format/tree/master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows&_configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows&_configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Linux&_configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Linux&_configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows_Spanish&_configuration=debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|[![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/format/dotnet.format?branchName=master&jobName=Windows_Spanish&_configuration=release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=347&branchName=master)|


`dotnet-format` is a code formatter for `dotnet` that applies style preferences to a project or solution. Preferences will be read from an `.editorconfig` file, if present, otherwise a default set of preferences will be used. At this time `dotnet-format` is able to format C# and Visual Basic projects with a subset of [supported .editorconfig options](./docs/Supported-.editorconfig-options.md).

### New in v4.0.130203

#### Breaking Changes:
- Added an imports formatter for sorting imports.
- Format now runs on the latest installed Runtime.
Expand All @@ -38,7 +39,6 @@
- [Support loading commandline options from response files (552)](https://github.com/dotnet/format/pull/552)
- [Support file globbing in --include and --exclude options (555)](https://github.com/dotnet/format/pull/555)


### How To Install

The `dotnet-format` nuget package is [published to nuget.org](https://www.nuget.org/packages/dotnet-format/).
Expand All @@ -56,25 +56,30 @@ Development builds of `dotnet-format` are being hosted on myget. You can visit t
You can install the tool using the following command.

```console
dotnet tool install -g dotnet-format --version 4.0.111308 --add-source https://dotnet.myget.org/F/format/api/v3/index.json
dotnet tool install -g dotnet-format --version 5.0.135301 --add-source https://dotnet.myget.org/F/format/api/v3/index.json
```

### How To Use

By default `dotnet-format` will look in the current directory for a project or solution file and use that as the workspace to format. If more than one project or solution file is present in the current directory you will need to specify the workspace to format using the `-w` or `-f` options. You can control how verbose the output will be by using the `-v` option.

```sh
```console
Usage:
dotnet-format <project> [options]
dotnet-format [options] [<workspace>]

Arguments:
<workspace> A path to a solution file, a project file, or a folder containing a solution or project file. If a path is not specified then the current directory is used.

Options:
--folder, -f Whether to treat the `<project>` path as a folder of files.
--include <INCLUDE> A list of relative file or folder paths to include in formatting. All files are formatted if empty.
--exclude <EXCLUDE> A list of relative file or folder paths to exclude from formatting.
--check <CHECK> Formats files without saving changes to disk. Terminates with a non-zero exit code if any files were formatted.
--report <REPORT> Accepts a file path, which if provided, will produce a json report in the given directory.
--verbosity, -v <VERBOSITY> Set the verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]
--version Display version information
--folder, -f Whether to treat the `<workspace>` argument as a simple folder of files.
--fix-style, -fs <severity> Run code style analyzers and apply fixes.
--fix-analyzers, -fa <severity> Run 3rd party analyzers and apply fixes.
--include <include> A list of relative file or folder paths to include in formatting. All files are formatted if empty.
--exclude <exclude> A list of relative file or folder paths to exclude from formatting.
--check Formats files without saving changes to disk. Terminates with a non-zero exit code if any files were formatted.
--report <report> Accepts a file path, which if provided, will produce a json report in the given directory.
--verbosity, -v <verbosity> Set the verbosity level. Allowed values are q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]
--version Show version information
```

Add `format` after `dotnet` and before the command arguments that you want to run:
Expand All @@ -83,7 +88,9 @@ Add `format` after `dotnet` and before the command arguments that you want to ru
| ---------------------------------------------------------- |---------------------------------------------------------------------------------------------- |
| dotnet **format** | Formats the project or solution in the current directory. |
| dotnet **format** &lt;workspace&gt; | Formats a specific project or solution. |
| dotnet **format** &lt;folder&gt; -f | Formats a particular folder and subfolders. |
| dotnet **format** &lt;workspace&gt; -f | Formats a particular folder and subfolders. |
| dotnet **format** &lt;workspace&gt; --fix-style warn | Formats and fixes codestyle analyzer warnings. |
| dotnet **format** &lt;workspace&gt; --fix-analyzers | Formats and fixes 3rd party analyzer errors. |
| dotnet **format** -v diag | Formats with very verbose logging. |
| dotnet **format** --include Programs.cs Utility\Logging.cs | Formats the files Program.cs and Utility\Logging.cs |
| dotnet **format** --check | Formats but does not save. Returns a non-zero exit code if any files would have been changed. |
Expand All @@ -104,8 +111,8 @@ You can build and package the tool using the following commands. The instruction
```console
build -pack
# The final line from the build will read something like
# Successfully created package '..\artifacts\packages\Debug\Shipping\dotnet-format.4.0.0-dev.nupkg'.
# Use the value that is in the form `4.0.0-dev` as the version in the next command.
# Successfully created package '..\artifacts\packages\Debug\Shipping\dotnet-format.5.0.0-dev.nupkg'.
# Use the value that is in the form `5.0.0-dev` as the version in the next command.
dotnet tool install --add-source .\artifacts\packages\Debug\Shipping -g dotnet-format --version <version>
dotnet format
```
Expand Down
39 changes: 39 additions & 0 deletions docs/3rd-party-analyzers.md
View file
@@ -0,0 +1,39 @@
# 3rd Party Analyzers

## How to add analyzers to a project

3rd party analyzers are discovered from the `<PackageReferences>` specified in the workspace project files.

*Example:*

Add the StyleCop analyzer package to a simple console project file.

```diff
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

+ <ItemGroup>
+ <PackageReference Include="StyleCop.Analyzers" Version="1.1.118" />
+ </ItemGroup>

</Project>
```

## How to configure analyzer severity

The options specified in .editorconfig files are recognized by the pattern `dotnet_diagnostic.<diagnostic-id>.severity = <value>`. `<diagnostic-id>` represents the diagnostic ID matched by the compiler, case-insensitively, to be configured. `<value>` must be one of the following: error, warn, info, hidden, suppress.

*Example:*

Configure the StyleCop analyzer so that empty comments are errors.

```ini
[*.{cs,vb}]

# The C# comment does not contain any comment text.
dotnet_diagnostic.SA1120.severity = error
```
61 changes: 57 additions & 4 deletions docs/README.md
View file
Expand Up @@ -2,16 +2,69 @@

## .editorconfig options
- [Supported .editorconfig options](./Supported-.editorconfig-options.md)
- [Unsupported Code Style options](./Unsupported-Code-Style-options.md)

## CLI options

### Specify a workspace (Required)

A project path is needed when running dotnet-format. By default, the current folder will be used as the project path. The project path and type of project determines which code files are considered for formatting.
A workspace path is needed when running dotnet-format. By default, the current folder will be used as the workspace path. The workspace path and type of workspace determines which code files are considered for formatting.

- Solutions and Projects - By default dotnet-format will open the project path as a MSBuild solution or project.
- `--folder` - When the folder options is specified the project path will be treated as a folder of code files.
- Solutions and Projects - By default dotnet-format will open the workspace path as a MSBuild solution or project.
- `--folder` - When the folder options is specified the workspace path will be treated as a folder of code files.

*Example:*

Format the code files used in the format solution.

```console
dotnet-format ./format.sln
```

Format the code files used in the dotnet-format project.

```console
dotnet-format ./src/dotnet-format.csproj
```

Format the code files from the `./src` folder.

```console
dotnet-format ./src --folder
```

### Running analysis

#### CodeStyle analysis

Running codestyle analysis requires the use of a MSBuild solution or project file as the workspace. Enforces the .NET [Language conventions](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-language-conventions?view=vs-2019) and [Naming conventions](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-naming-conventions?view=vs-2019).

- `--fix-style <severity>` - Runs analysis and attempts to fix issues with severity equal or greater than specified. If severity is not specified then severity defaults to error.

*Example:*

Run analysis against the format solution and fix errors.

```console
dotnet-format ./format.sln --fix-style
```

Run analysis against the dotnet-format project and fix warnings and errors.

```console
dotnet-format ./src/dotnet-format.csproj --fix-style warn
```

Errors when used with the `--folder` option. Analysis requires a MSBuild solution or project.

```console
dotnet-format ./src --folder --fix-style
```

#### 3rd party analysis

Running 3rd party analysis requires the use of a MSBuild solution or project file as the workspace. 3rd party analyzers are discovered from the `<PackageReferences>` specified in the workspace project files.

- `--fix-analyzers <severity>` - Runs analysis and attempts to fix issues with severity equal or greater than specified. If no severity is specified then this defaults to error.

### Filter files to format

Expand Down
63 changes: 5 additions & 58 deletions docs/Supported-.editorconfig-options.md
View file
@@ -1,5 +1,7 @@
The dotnet-format global tool supports the core set of EditorConfig options*:
# Supported .editorconfig options
The dotnet-format global tool supports the core set of [EditorConfig options](https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties)* as well as the [.NET coding convention settings for EditorConfig](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2019)**.

## Core options
- indent_style
- indent_size
- tab_width
Expand All @@ -8,61 +10,6 @@ The dotnet-format global tool supports the core set of EditorConfig options*:
- insert_final_newline
- root

[*] The option trim_trailing_whitespace is not supported. Currently insignificant whitespace is **always** removed by the formatter.
[*] The options `trim_trailing_whitespace` and `max_line_length` are not supported. Currently insignificant whitespace is **always** removed by the formatter.

In addition dotnet-format supports a subset of the [.NET coding convention settings for EditorConfig](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference?view=vs-2017).

# Formatting conventions
Most of the rules for formatting conventions have the following format:

`rule_name = false|true`

You specify either `true` (prefer this style) or `false` (do not prefer this style). You do not specify a severity. For a few rules, instead of `true` or `false`, you specify other values to describe when and where to apply the rule.

## C# formatting settings
The formatting rules in this section apply only to C# code.

**Newline options**
These formatting rules concern the use of new lines to format code.

- csharp_new_line_before_open_brace (default value: `all`)
- csharp_new_line_before_else (default value: `true`)
- csharp_new_line_before_catch (default value: `true`)
- csharp_new_line_before_finally (default value: `true`)
- csharp_new_line_before_members_in_object_initializers (default value: `true`)
- csharp_new_line_before_members_in_anonymous_types (default value: `true`)
- csharp_new_line_between_query_expression_clauses (default value: `true`)

**Indentation options**
These formatting rules concern the use of indentation to format code.

- csharp_indent_case_contents (default value: `true`)
- csharp_indent_switch_labels (default value: `true`)
- csharp_indent_labels (default value: `no_change`)

**Spacing options**
These formatting rules concern the use of space characters to format code.

- csharp_space_after_cast (default value: `false`)
- csharp_space_after_keywords_in_control_flow_statements (default value: `true`)
- csharp_space_between_method_declaration_parameter_list_parentheses (default value: `false`)
- csharp_space_between_method_call_parameter_list_parentheses (default value: `false`)
- csharp_space_between_parentheses (default value: `false`)
- csharp_space_before_colon_in_inheritance_clause (default value: `true`)
- csharp_space_after_colon_in_inheritance_clause (default value: `true`)
- csharp_space_around_binary_operators (default value: `before_and_after`)
- csharp_space_between_method_declaration_empty_parameter_list_parentheses (default value: `false`)
- csharp_space_between_method_call_name_and_opening_parenthesis (default value: `false`)
- csharp_space_between_method_call_empty_parameter_list_parentheses (default value: `false`)

**Wrapping options**
These formatting rules concern the use of single lines versus separate lines for statements and code blocks.

- csharp_preserve_single_line_statements (default value: `true`)
- csharp_preserve_single_line_blocks (default value: `true`)

**Organize using directives**
These formatting rules concern the sorting and display of using directives and Imports statements.

- dotnet_sort_system_directives_first (default value: `true`)
- dotnet_separate_import_directive_groups (default value: `true`)
[**] [Formatting conventions](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-formatting-conventions?view=vs-2019) are enforced by default. Use the `--fix-style` option to enforce [Language conventions](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-language-conventions?view=vs-2019) and [Naming conventions](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-naming-conventions?view=vs-2019).

0 comments on commit bc6d17b

Please sign in to comment.