Update markdown files to comply to markdown guidelines

GuidelinesForNewRules.md

@@ -1,5 +1,6 @@
-Guidelines for contributing a new Code Analysis (CA) rule to the repo
-=================================================================
+# Contribution Guidelines
+
+## Guidelines for contributing a new Code Analysis (CA) rule to the repo
 
 1. File an issue describing your proposed rule prior to working on a PR. This will ensure that the rule gets triaged and there is no duplicate work involved from an existing rule OR another contributor working on a similar rule.
    1. For .NET API related analyzer suggestions, please open an issue at [dotnet/runtime/issues](https://github.com/dotnet/runtime/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) with [code-analyzer](https://github.com/dotnet/runtime/issues?q=is%3Aopen+is%3Aissue+label%3Acode-analyzer+sort%3Aupdated-desc) label.
@@ -24,25 +25,25 @@
    3. A good rule of thumb is that if your analyzer needs to invoke `GetTypeByMetadataName`, then most likely it is an API specific analyzer and belongs to `Microsoft.NetCore.Analyzers`.
 
 5. Documentation requirements:
-   1. **New CA rule must be documented**: Each rule ID `CAxxxx` is automatically assigned the help link https://docs.microsoft.com/visualstudio/code-quality/caxxxx. The documentation for this page is populated from `caxxxx.md` file at https://github.com/MicrosoftDocs/visualstudio-docs/tree/master/docs/code-quality. For example, `CA1000` is documented at [ca1000.md](https://github.com/MicrosoftDocs/visualstudio-docs/blob/master/docs/code-quality/ca1000.md) file. Documenting a new rule is primarily ensuring a PR is sent to `MicrosoftDocs` repo to add `caxxxx.md` file for the new rule. Detailed steps are given below.
+   1. **New CA rule must be documented**: Each rule ID `CAxxxx` is automatically assigned the help link `https://docs.microsoft.com/visualstudio/code-quality/caxxxx`. The documentation for this page is populated from `caxxxx.md` file at [visualstudio-docs code-quality folder](https://github.com/MicrosoftDocs/visualstudio-docs/tree/master/docs/code-quality). For example, `CA1000` is documented at [ca1000.md](https://github.com/MicrosoftDocs/visualstudio-docs/blob/master/docs/code-quality/ca1000.md) file. Documenting a new rule is primarily ensuring a PR is sent to `MicrosoftDocs` repo to add `caxxxx.md` file for the new rule. Detailed steps are given below.
    2. **Documentation PR must be submitted within ONE WEEK of the rule implementation being merged**. Note that we will communicate this requirement on each PR contributing a new CA rule. We reserve the right to revert the rule implementation PR if this documentation requirement is not met.
-   
-   Steps for creating documentation PR:
-   
-   1. Documentation PR must be submitted to the following repo:
-      1. _External contributors_: https://github.com/MicrosoftDocs/visualstudio-docs
-      2. _Internal contributors_: https://github.com/MicrosoftDocs/visualstudio-docs-pr
-      
-      Please review [CONTRIBUTING.md](https://github.com/MicrosoftDocs/visualstudio-docs/blob/master/CONTRIBUTING.md) for guidelines.
-   2. Documentation PR for a new CA rule must have following changes:
-      1. New `caxxxx.md` file under `/docs/code-quality` sub-folder with rule documentation.
-         
-         `TIP:` Clone an existing `caxxxx.md` file inside `/docs/code-quality` sub-folder in the repo, rename it and update the contents for the new rule.
-      2. Update the following tables in the repo for supported CA rule IDs:
-         1. Add entry in `/docs/code-quality/toc.yml` under appropriate category.
-         2. Add entry in `/docs/code-quality/code-analysis-warnings-for-managed-code-by-checkid.md`
-         3. Add entry in the documentation file `/docs/code-quality/<%category%>-warnings.md` for rule's `Category`. For example:
-            1. For a new rule with category `Design`, add an entry to `/docs/code-quality/design-warnings.md`.
-            2. For a new rule with category `Performance`, add an entry to `/docs/code-quality/performance-warnings.md`, and so on.
-    
-   If for some exceptional reason you are unable to submit a PR, please [file a documentation issue](https://github.com/MicrosoftDocs/visualstudio-docs/issues) to add documentation for the rule in future. Please include all relevant information in the issue to allow the documentation experts to easily author the documentation. For example, see [this issue](https://github.com/MicrosoftDocs/visualstudio-docs/issues/3454).
+
+## Guidelines for creating documentation PR
+
+1. Documentation PR must be submitted to the following repo:
+   1. [_External contributors_](https://github.com/MicrosoftDocs/visualstudio-docs)
+   2. [_Internal contributors_](https://github.com/MicrosoftDocs/visualstudio-docs-pr)
+
+   Please review [CONTRIBUTING.md](https://github.com/MicrosoftDocs/visualstudio-docs/blob/master/CONTRIBUTING.md) for guidelines.
+2. Documentation PR for a new CA rule must have following changes:
+   1. New `caxxxx.md` file under `/docs/code-quality` sub-folder with rule documentation.
+
+      `TIP:` Clone an existing `caxxxx.md` file inside `/docs/code-quality` sub-folder in the repo, rename it and update the contents for the new rule.
+   2. Update the following tables in the repo for supported CA rule IDs:
+      1. Add entry in `/docs/code-quality/toc.yml` under appropriate category.
+      2. Add entry in `/docs/code-quality/code-analysis-warnings-for-managed-code-by-checkid.md`
+      3. Add entry in the documentation file `/docs/code-quality/<%category%>-warnings.md` for rule's `Category`. For example:
+         1. For a new rule with category `Design`, add an entry to `/docs/code-quality/design-warnings.md`.
+         2. For a new rule with category `Performance`, add an entry to `/docs/code-quality/performance-warnings.md`, and so on.
+
+If for some exceptional reason you are unable to submit a PR, please [file a documentation issue](https://github.com/MicrosoftDocs/visualstudio-docs/issues) to add documentation for the rule in future. Please include all relevant information in the issue to allow the documentation experts to easily author the documentation. For example, see [this issue](https://github.com/MicrosoftDocs/visualstudio-docs/issues/3454).

PostReleaseActivities.md

@@ -1,5 +1,6 @@
-Post-release activities
-=================================================================
+# Post-release activities
+
+## Steps to generate Packages
 
 Please follow the below steps after publishing analyzer NuGet packages from this repo onto NuGet.org:
 
@@ -20,8 +21,7 @@ Please follow the below steps after publishing analyzer NuGet packages from this
    7. Move all the entries from `AnalyzerReleases.Unshipped.md` to `AnalyzerReleases.Shipped.md` for various analyzer NuGet package projects under a new "Release" section in the shipped file.
    8. Create and submit a PR with the above changes.
 
-Steps to generate Release Notes
-=================================================================
+## Steps to generate Release Notes
 
 1. Checkout the sources for the release branch locally. This would normally be the master branch.
 2. Build.

README.md

@@ -4,17 +4,19 @@
 |:--------:|:-----------:|:-------------:|
 |**master**| [![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/roslyn-analyzers/roslyn-analyzers-CI?branchName=master&jobName=Windows&configuration=Windows%20Debug&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=457&branchName=master) [![codecov](https://codecov.io/gh/dotnet/roslyn-analyzers/branch/master/graph/badge.svg)](https://codecov.io/gh/dotnet/roslyn-analyzers) | [![Build Status](https://dev.azure.com/dnceng/public/_apis/build/status/dotnet/roslyn-analyzers/roslyn-analyzers-CI?branchName=master&jobName=Windows&configuration=Windows%20Release&label=build)](https://dev.azure.com/dnceng/public/_build/latest?definitionId=457&branchName=master) |
 
-# What is Roslyn?
+## What is Roslyn?
 
 Roslyn is the compiler platform for .NET. It consists of the compiler itself and a powerful set of APIs to interact with the compiler. The Roslyn platform is hosted at [github.com/dotnet/roslyn](https://github.com/dotnet/roslyn).
 
-# What are Roslyn Analyzers?
+## What are Roslyn Analyzers?
 
 Roslyn analyzers analyze your code for style, quality and maintainability, design and other issues. The documentation for Roslyn Analyzers can be found at [docs.microsoft.com/visualstudio/code-quality/roslyn-analyzers-overview](https://docs.microsoft.com/visualstudio/code-quality/roslyn-analyzers-overview).
 
 Microsoft created a set of analyzers called [Microsoft.CodeAnalysis.FxCopAnalyzers](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers) that contains the most important "FxCop" rules from static code analysis, converted to Roslyn analyzers. These analyzers check your code for security, performance, and design issues, among others. The documentation for FxCop analyzers in Visual Studio can be found at [docs.microsoft.com/visualstudio/code-quality/install-fxcop-analyzers](https://docs.microsoft.com/visualstudio/code-quality/install-fxcop-analyzers).
 
-# Microsoft.CodeAnalysis.NetAnalyzers
+## Main analyzers
+
+### Microsoft.CodeAnalysis.NetAnalyzers
 
 *Latest stable version:* _Not yet released_
 
@@ -40,7 +42,7 @@ You do not need to manually install this NuGet package to your project if you ar
    </PropertyGroup>
    ```
 
-# Microsoft.CodeAnalysis.FxCopAnalyzers
+### Microsoft.CodeAnalysis.FxCopAnalyzers
 
 *Latest stable version:* [![NuGet](https://img.shields.io/nuget/v/Microsoft.CodeAnalysis.FxCopAnalyzers.svg)](https://www.nuget.org/packages/Microsoft.CodeAnalysis.FxCopAnalyzers)
 
@@ -52,17 +54,17 @@ The documentation for all the ported and unported FxCop rules can be found at [d
 
 This analyzer package contains all the ported FxCop rules that are applicable for both _.NetCore/.NetStandard_ and _Desktop .NetFramework_ projects. You **do not need to install any separate analyzer package from this repo to get target-framework specific FxCop rules**. [More info about rules in this package](src/Microsoft.CodeAnalysis.FxCopAnalyzers/Microsoft.CodeAnalysis.FxCopAnalyzers.md)
 
-## The following are subpackages or NuGet dependencies that are automatically installed when you install the Microsoft.CodeAnalysis.FxCopAnalyzers package:
+#### The following are subpackages or NuGet dependencies that are automatically installed when you install the Microsoft.CodeAnalysis.FxCopAnalyzers package:
 
-### Microsoft.CodeQuality.Analyzers
+#### Microsoft.CodeQuality.Analyzers
 
 *Latest stable version:* [![NuGet](https://img.shields.io/nuget/v/Microsoft.CodeQuality.Analyzers.svg)](https://www.nuget.org/packages/Microsoft.CodeQuality.Analyzers)
 
 *Latest pre-release version:* [here](https://dev.azure.com/dnceng/public/_packaging?_a=package&feed=dotnet5&package=Microsoft.CodeQuality.Analyzers&protocolType=NuGet)
 
 This package contains common code quality improvement rules that are not specific to usage of any particular API. For example, [CA1801](https://docs.microsoft.com/visualstudio/code-quality/ca1801-review-unused-parameters) (ReviewUnusedParameters) flags parameters that are unused and is part of this package. [More info about rules in this package](src/Microsoft.CodeQuality.Analyzers/Microsoft.CodeQuality.Analyzers.md)
 
-### Microsoft.NetCore.Analyzers
+#### Microsoft.NetCore.Analyzers
 
 *Latest stable version:* [![NuGet](https://img.shields.io/nuget/v/Microsoft.NetCore.Analyzers.svg)](https://www.nuget.org/packages/Microsoft.NetCore.Analyzers)
 
@@ -72,7 +74,7 @@ This package contains rules for correct usage of APIs that are present in _.NetC
 
 **NOTE:** This analyzer package is applicable for both _.NetCore/.NetStandard_ and _Desktop .NetFramework_ projects. If the API whose usage is being checked exists only in _.NetCore/.NetStandard_ libraries, then the analyzer will bail out silently for _Desktop .NetFramework_ projects. Otherwise, if the API exists in both _.NetCore/.NetStandard_ and _Desktop .NetFramework_ libraries, the analyzer will run correctly for both  _.NetCore/.NetStandard_ and _Desktop .NetFramework_ projects. [More info about rules in this package](src/Microsoft.NetCore.Analyzers/Microsoft.NetCore.Analyzers.md)
 
-### Microsoft.NetFramework.Analyzers
+#### Microsoft.NetFramework.Analyzers
 
 *Latest stable version:* [![NuGet](https://img.shields.io/nuget/v/Microsoft.NetFramework.Analyzers.svg)](https://www.nuget.org/packages/Microsoft.NetFramework.Analyzers)
 
@@ -82,7 +84,7 @@ This package contains rules for correct usage of APIs that are present only in _
 
 **NOTE:** The analyzers in this package will silently bail out if installed on a _.NetCore/.NetStandard_ project that do not have the underlying API whose usage is being checked. If future versions of _.NetCore/.NetStandard_ libraries include these APIs, the analyzers will automatically light up on _.NetCore/.NetStandard_ projects that target these libraries. [More info about rules in this package](src/Microsoft.NetFramework.Analyzers/Microsoft.NetFramework.Analyzers.md)
 
-# Other Analyzer Packages
+## Other Analyzer Packages
 
 ### Microsoft.CodeAnalysis.Analyzers
 
@@ -126,7 +128,7 @@ The MetaCompilation Analyzer is an analyzer that functions as a tutorial to teac
 
 For instructions on using this tutorial, see [Instructions](https://github.com/dotnet/roslyn-analyzers/blob/master/src/MetaCompilation.Analyzers/Core/ReadMe.md#instructions).
 
-# Getting Started
+## Getting Started
 
 1. Install Visual Studio 2019 or later, with at least the following workloads:
    1. .NET desktop development
@@ -138,19 +140,19 @@ For instructions on using this tutorial, see [Instructions](https://github.com/d
 5. Run the restore and build command: `build.cmd`(in the command prompt) or `.\build.cmd`(in PowerShell).
 6. Execute tests: `test.cmd`(in the command prompt) or `.\test.cmd`(in PowerShell).
 
-# Submitting Pull Requests
+## Submitting Pull Requests
 
 Prior to submitting a pull request, ensure the build and all tests pass using using steps 4 and 5 above.
 
-# Guidelines for contributing a new Code Analysis (CA) rule to the repo
+## Guidelines for contributing a new Code Analysis (CA) rule to the repo
 
 See [GuidelinesForNewRules.md](.//GuidelinesForNewRules.md) for contributing a new Code Analysis rule to the repo.
 
-# Versioning Scheme for Analyzer Packages
+## Versioning Scheme for Analyzer Packages
 
 See [VERSIONING.md](.//VERSIONING.md) for the versioning scheme for all analyzer packages built out of this repo.
 
-# Recommended version of Analyzer Packages
+## Recommended version of Analyzer Packages
 
 Recommended Visual Studio Version: **Visual Studio 2019 16.3 RTW or later**
 

SECURITY.md

@@ -6,10 +6,11 @@ The .NET Core and ASP.NET Core support policy, including supported versions can
 
 ## Reporting a Vulnerability
 
-Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC), either by emailing [email protected] or via the portal at https://msrc.microsoft.com. 
-You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your 
+Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC), either by emailing [email protected] or via the portal at
+[https://msrc.microsoft.com](https://msrc.microsoft.com).
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your
 original message. Further information, including the MSRC PGP key, can be found in the [MSRC Report an Issue FAQ](https://www.microsoft.com/en-us/msrc/faqs-report-an-issue).
 
 Reports via MSRC may qualify for the .NET Core Bug Bounty. Details of the .NET Core Bug Bounty including terms and conditions are at [https://aka.ms/corebounty](https://aka.ms/corebounty).
 
-Please do not open issues for anything you think might have a security implication.
+Please do not open issues for anything you think might have a security implication.

VERSIONING.md

@@ -1,5 +1,4 @@
-Versioning scheme for .NET Compiler Platform ("Roslyn") Analyzers
-=================================================================
+# Versioning scheme for .NET Compiler Platform ("Roslyn") Analyzers
 
 Following is the versioning scheme that is being used for analyzer packages:
 
@@ -9,8 +8,7 @@ Following is the versioning scheme that is being used for analyzer packages:
 
 **NOTE**: An exception was applied to the above versioning scheme when we moved the analyzer packages to version 1.1.0, while still depending on version 1.0.0 of Microsoft.CodeAnalysis. This was done as we had mistakenly published 1.1.0-beta1 pre-release packages for some analyzer packages on nuget.org.
 
-Current and Released Versions of Analyzer Packages
-==================================================
+## Current and Released Versions of Analyzer Packages
 
 Current version of all analyzer packages that are built out of this repo are tracked by the `VersionPrefix` property defined in [Versions.Props](.//eng//Versions.props)
 

docs/Analyzer Configuration.md

@@ -263,7 +263,7 @@ Option Name: `excluded_symbol_names`
 Configurable Rules:
 [CA1303](https://docs.microsoft.com/visualstudio/code-quality/ca1303),
 [CA1062](https://docs.microsoft.com/visualstudio/code-quality/ca1062),
-[CA1304](https://docs.microsoft.com/visualstudio/code-quality/ca1304), 
+[CA1304](https://docs.microsoft.com/visualstudio/code-quality/ca1304),
 [CA1508](https://docs.microsoft.com/visualstudio/code-quality/ca1508),
 [CA2000](https://docs.microsoft.com/visualstudio/code-quality/ca2000),
 [CA2100](https://docs.microsoft.com/visualstudio/code-quality/ca2100),
@@ -404,7 +404,7 @@ Configurable Rules:
 [CA1508](https://docs.microsoft.com/visualstudio/code-quality/ca1508),
 [CA2000](https://docs.microsoft.com/visualstudio/code-quality/ca2000),
 [CA2100](https://docs.microsoft.com/visualstudio/code-quality/ca2100),
-[CA2213](https://docs.microsoft.com/visualstudio/code-quality/ca2213), 
+[CA2213](https://docs.microsoft.com/visualstudio/code-quality/ca2213),
 Taint analysis rules
 
 #### Interprocedural analysis Kind
@@ -528,6 +528,7 @@ class Test
 ```
 
 #### Points to analysis kind for DFA rules based on PointsToAnalysis
+
 Option Name: `points_to_analysis_kind`
 
 Configurable Rules: All DFA rules
@@ -696,6 +697,7 @@ Default Value: Namespace, NamedType, Method, Property, Event, Parameter
 Example: `dotnet_code_quality.CA1716.analyzed_symbol_kinds = Namespace, Property`
 
 ### Use naming heuristic
+
 Option Name: `use_naming_heuristic`
 
 Configurable Rules: [CA1303](https://docs.microsoft.com/en-us/visualstudio/code-quality/ca1303)
@@ -707,14 +709,16 @@ Default Value: `false`
 Example: `dotnet_code_quality.CA1303.use_naming_heuristic = true`
 
 ### Additional use results methods
+
 Option Name: `additional_use_results_methods`
 
 Configurable Rules: [CA1806](https://docs.microsoft.com/en-us/visualstudio/code-quality/CA1806)
 
 Option Values: Names of additional methods (separated by '|') for CA1806.
 Allowed method name formats:
+
   1. Method name only (includes all methods with the name, regardless of the containing type or namespace)
-  2. Fully qualified names in the symbol's documentation ID format: https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md#id-string-format
+  2. Fully qualified names in the [symbol's documentation ID format](https://github.com/dotnet/csharplang/blob/master/spec/documentation-comments.md#id-string-format)
      with an optional "M:" prefix.
 
 Default Value: None
@@ -729,6 +733,7 @@ Examples:
 |`dotnet_code_quality.CA1806.additional_use_results_methods = M:NS1.MyType1.MyMethod1(ParamType)\|M:NS2.MyType2.MyMethod2(ParamType)` | Matches specific methods 'MyMethod1' and 'MyMethod2' with respective fully qualified signature
 
 ### Allowed suffixes
+
 Option Name: `allowed_suffixes`
 
 Configurable Rules: [CA1711](https://docs.microsoft.com/visualstudio/code-quality/ca1711)