Merge pull request #1579 from vweijsters/fix-1358

Author: sharwell

documentation/SA1636.md

@@ -21,18 +21,79 @@ The file header at the top of a C# code file does not contain the appropriate co
 
 ## Rule description
 
-A violation of this rule occurs when the file header at the top of a C# file does not contain the copyright text that has been specified for the project. To enable this rule, navigate to the StyleCop settings for the project and change to the Company Information tab, as shown below:
+A violation of this rule occurs when the file header at the top of a C# file does not contain the copyright text that has been specified for the project.
 
-![](Images/CompanyInformationSettings.JPG)
+In order to enable this rule, the `copyrightText` property must have been specified. See the [configuration](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md) section for details on how to set this up.
 
-Check the checkbox at the top of the settings page, and fill in the required copyright text for your company. Click OK to save the settings. With these settings in place, every file within the project must contain the required copyright text within its file header copyright tag, as shown in the example below:
+The value of the `xmlHeader` property will influence the behavior of this rule. When the `xmlHeader` property is **true** (the default), StyleCop Analyzers expects file headers to conform to the following standard StyleCop format.
 
 ```csharp
-//-----------------------------------------------------------------------
-// <copyright file="Widget.cs" company="My Company">
-//     Custom company copyright tag.
+// <copyright file="{fileName}" company="{companyName}">
+// {copyrightText}
 // </copyright>
-//-----------------------------------------------------------------------
+```
+
+When the `xmlHeader` property is explicitly set to **false**, StyleCop Analyzers expects file headers to conform to the following customizable format.
+
+```csharp
+// {copyrightText}
+```
+
+With these settings in place, every file within the project must contain the required copyright text in the format described above.
+
+### Comment styles
+This rule will accept several comment styles. The examples below give an overview of accepted styles.
+
+Examples with the `xmlHeader` property set to **true**
+```csharp
+// <copyright file="{fileName}" company="{companyName}">
+// {copyrightText}
+// </copyright>
+```
+
+```csharp
+// ----------------------------------------------------------------------
+// <copyright file="{fileName}" company="{companyName}">
+// {copyrightText}
+// </copyright>
+// ----------------------------------------------------------------------
+```
+
+```csharp
+/* <copyright file="{fileName}" company="{companyName}">
+ * {copyrightText}
+ * </copyright>
+ */
+```
+
+```csharp
+/*
+  <copyright file="{fileName}" company="{companyName}">
+  {copyrightText}
+  </copyright>
+*/
+```
+
+Examples with the `xmlHeader` property set to **false**
+
+```csharp
+// {copyrightText}
+```
+
+```csharp
+/* {copyrightText} */
+```
+
+```csharp
+/*
+ * {copyrightText}
+ */
+```
+
+```csharp
+/*
+  {copyrightText}
+*/
 ```
 
 ## How to fix violations

documentation/SA1641.md

@@ -21,11 +21,12 @@ The file header at the top of a C# code file does not contain the appropriate co
 
 ## Rule description
 
-A violation of this rule occurs when the file header at the top of a C# file does not contain the company name text that has been specified for the project. To enable this rule, navigate to the StyleCop settings for the project and change to the Company Information tab, as shown below:
+A violation of this rule occurs when the file header at the top of a C# file does not contain the company name text that has been specified for the project.
 
-![](Images/CompanyInformationSettings.JPG)
+In order to enable this rule, the `companyName` property must have been specified. In addition to that, the `xmlHeader` property must be either omitted or have a value of **true**.
+See the [configuration](https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/Configuration.md) section for details on how to set this up.
 
-Check the checkbox at the top of the settings page, and fill in the required company name text for your company. Click OK to save the settings. With these settings in place, every file within the project must contain the required company name text within its file header copyright tag, as shown in the example below:
+With these settings in place, every file within the project must contain the required company name text within its file header copyright tag, as shown in the example below:
 
 ```csharp
 //-----------------------------------------------------------------------