Merge branch 'master' into fix--MD005/list-indent

Author: nschonni

.markdownlint.json

@@ -14,7 +14,6 @@
     "MD027": false,
     "MD028": false,
     "MD029": false,
-    "MD031": false,
     "MD032": false,
     "MD033": {
         "allowed_elements": [

docs/ai/installation.md

@@ -81,6 +81,7 @@ Deep learning frameworks rely on pip for their own installation.
 Then, we need to verify whether Python 3.5 is installed correctly, and upgrade pip to the latest version by executing the following commands in a terminal:
 
 - **Windows**
+
     ```cmd
     C:\Users\test>python -V
     Python 3.5.4
@@ -92,6 +93,7 @@ Then, we need to verify whether Python 3.5 is installed correctly, and upgrade p
     ```
 
 - **macOS**
+
     ```bash
     MyMac:~ test$ python3.5 -V
     Python 3.5.4
@@ -153,10 +155,13 @@ Visit [here](https://caffe2.ai/docs/getting-started.html) to build from source c
 To install MXNet, run the following command in a terminal:
 
 - With GPU
+
     ```bash
     pip3.5 install mxnet-cu80==0.12.0
     ```
+
 - Without GPU
+
     ```bash
     pip3.5 install mxnet==0.12.0
     ```

docs/azure/vs-azure-tools-diagnostics-for-cloud-services-and-virtual-machines.md

@@ -148,6 +148,7 @@ If you're using Azure SDK 2.5 and want to specify a custom data source, you can
    <DataSource name="CustomDataSource!*" />
 </WindowsEventLog>
 ```
+
 ### Performance counters
 Performance counter information can help you locate system bottlenecks and fine-tune system and application performance. For more information, see [Create and use performance counters in an Azure application](https://msdn.microsoft.com/library/azure/hh411542.aspx). To capture performance counters, select the **Enable transfer of Performance Counters** check box. To increase or decrease the interval between the transfer of event logs to your storage account, change the **Transfer Period (min)** value. Select the check boxes for the performance counters that you want to track.
 

docs/azure/vs-azure-tools-optimizing-azure-code-in-visual-studio.md

@@ -209,6 +209,7 @@ while (true)
    }
 }
 ```
+
 ## Consider using asynchronous Service Bus methods
 ### ID
 AP2003

docs/azure/vs-azure-tools-resource-groups-ci.md

@@ -166,6 +166,7 @@ The following procedures walk you through the steps necessary to configure conti
      ```
      -_artifactsLocation $(artifactsLocation) -_artifactsLocationSasToken (ConvertTo-SecureString -String "$(artifactsLocationSasToken)" -AsPlainText -Force)
      ```
+
      ![Configure Azure Resource Group Deployment Task](media/vs-azure-tools-resource-groups-ci-in-vsts/walkthrough18.png)
 7. After you’ve added all the required items, save the build pipeline and choose **Queue new build** at the top.
 

docs/code-quality/C26404.md

@@ -18,6 +18,7 @@ Once owner pointer releases or transfers its resource, it gets into an "invalid"
 Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer.
 
 ## Example 1: Deleting an owner after transferring its value
+
 ```cpp
 gsl::owner<State*> validState = nullptr;
 gsl::owner<State*> state = ReadState();
@@ -27,6 +28,7 @@ if (!IsValid(state))
 ```
 
 ## Example 2: Deleting an uninitialized owner
+
 ```cpp
 gsl::owner<Message*> message;
 if (popLast)

docs/code-quality/C26405.md

@@ -17,6 +17,7 @@ ms.workload:
 If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn’t release resources).
 
 ## Example 1: Overwriting an owner in a loop
+
 ```cpp
 gsl::owner<Shape*> shape = nullptr;
 while (shape = NextShape()) // C26405

docs/code-quality/C26406.md

@@ -17,6 +17,7 @@ ms.workload:
 Owners are initialized from allocations or from other owners. Assigning a value from a raw pointer to an owner pointer is not allowed. Raw pointers don’t guarantee ownership transfer; there is still may be an original owner which holds the resource and will attempt to release it. Note that assigning a value from owner to a raw pointer is fine; raw pointers are valid clients to access resources, but not to manage them.
 
 ## Example 1:  Using address of object
+
 ```cpp
 gsl::owner<Socket*> socket = defaultSocket ? &defaultSocket : new Socket(); // C26406
 ```

docs/code-quality/C26407.md

@@ -23,26 +23,31 @@ To avoid unnecessary use of pointers we try to detect common patterns of local a
 - The pattern is detected only for local variables, so we don’t warn on cases where an allocation is assigned to, say, a global variable and then deleted in the same function.
 
 ## Example 1: Unnecessary object allocation on heap
+
 ```cpp
 auto tracer = new Tracer();
 ScanObjects(tracer);
 delete tracer;  // C26407
 ```
 
 ## Example 2: Unnecessary object allocation on heap (fixed with local object)
+
 ```cpp
 Tracer tracer;  // OK
 ScanObjects(&tracer);
 ```
 
 ## Example 3: Unnecessary buffer allocation on heap
+
 ```cpp
 auto value = new char[maxValueSize];
 if (ReadSetting(name, value, maxValueSize))
     CheckValue(value);
 delete[] value; // C26407
 ```
+
 ## Example 4: Unnecessary buffer allocation on the heap (fixed with container)
+
 ```cpp
 auto value = std::vector<char>(maxValueSize); // OK
 if (ReadSetting(name, value.data(), maxValueSize))

docs/code-quality/C26410.md

@@ -21,6 +21,7 @@ Generally, references to const unique pointer are meaningless. They can safely b
 - Template code may produce a lot of noise. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed.
 
 ## Example 1: Unnecessary reference
+
 ```cpp
 std::vector<std::unique_ptr<Tree>> roots = GetRoots();
 std::for_each(

docs/code-quality/C26450.md

@@ -30,6 +30,7 @@ int multiply()
     return c;
 }
 ```
+
  To correct this warning, use the following code.
 
 ```cpp
@@ -53,6 +54,7 @@ int add()
     return c;
 }
 ```
+
  To correct this warning, use the following code:
 
 ```cpp
@@ -64,6 +66,7 @@ long long add()
     return c;
 }
 ```
+
 ## Example 3
 
 ```cpp
@@ -75,6 +78,7 @@ int subtract()
     return c;
 }
 ```
+
  To correct this warning, use the following code.
 
 ```cpp

docs/code-quality/C26451.md

@@ -30,6 +30,7 @@ void leftshift(int i)
   // code
 }
 ```
+
 To correct this warning, use the following code:
 
 ```cpp
@@ -41,6 +42,7 @@ void leftshift(int i)
   // code
 }
 ```
+
 ## Example 2
 
 ```cpp

docs/code-quality/C26452.md

@@ -26,6 +26,7 @@ unsigned __int64 combine(unsigned lo, unsigned hi)
   return (hi << 32) | lo; // C26252 here
 }
 ```
+
  To correct this warning, use the following code:
 
 ```cpp

docs/code-quality/C26454.md

@@ -26,6 +26,7 @@ unsigned int negativeunsigned()
     return x;
 }
 ```
+
  To correct this warning, use the following code:
 
 ```cpp

docs/code-quality/c28112.md

@@ -30,6 +30,7 @@ inter_var --;
 ...
 InterlockedIncrement(&inter_var);
 ```
+
 The following code example avoids this warning:
 
 ```cpp

docs/code-quality/ca2104-do-not-declare-read-only-mutable-reference-types.md

@@ -1,5 +1,5 @@
 ---
-title: "CA2104: Do not declare read only mutable reference types"
+title: "CA2104: Do not declare read-only mutable reference types"
 ms.date: 11/01/2018
 ms.topic: reference
 f1_keywords:
@@ -29,7 +29,7 @@ ms.workload:
 |Breaking Change|Non-breaking|
 
 > [!NOTE]
-> Rule CA2104 is obsolete and will be removed in a future version of Visual Studio.
+> Rule CA2104 is obsolete and will be removed in a future version of Visual Studio. It will not be implemented as an [analyzer](roslyn-analyzers-overview.md) due to the complicated analysis that's required to determine the actual immutability of a type.
 
 ## Cause
 

docs/code-quality/ca2300-do-not-use-insecure-deserializer-binaryformatter.md

@@ -35,18 +35,17 @@ This rule finds <xref:System.Runtime.Serialization.Formatters.Binary.BinaryForma
 - If possible, use a secure serializer instead, and **don't allow an attacker to specify an arbitrary type to deserialize**. Some safer serializers include:
   - <xref:System.Runtime.Serialization.DataContractSerializer?displayProperty=nameWithType>
   - <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer?displayProperty=nameWithType>
-  - <xref:System.Web.Script.Serialization.JavaScriptSerializer?displayProperty=nameWithType> - Never use <xref:System.Web.Script.Serialization.SimpleTypeResolver?displayProperty=nameWithType>. If you must use a type resolver, you must restrict deserialized types to an expected list.
+  - <xref:System.Web.Script.Serialization.JavaScriptSerializer?displayProperty=nameWithType> - Never use <xref:System.Web.Script.Serialization.SimpleTypeResolver?displayProperty=nameWithType>. If you must use a type resolver, restrict deserialized types to an expected list.
   - <xref:System.Xml.Serialization.XmlSerializer?displayProperty=nameWithType>
-  - NewtonSoft Json.NET - Use TypeNameHandling.None. If you must use another value for TypeNameHandling, then you must restrict deserialized types to an expected list.
+  - NewtonSoft Json.NET - Use TypeNameHandling.None. If you must use another value for TypeNameHandling, restrict deserialized types to an expected list with a custom ISerializationBinder.
   - Protocol Buffers
-- Make the serialized data tamper proof. After serialization, cryptographically sign the serialized data. Before deserializing, validate the cryptographic signature. You must protect the cryptographic key from being disclosed, and should design for key rotations.
+- Make the serialized data tamper-proof. After serialization, cryptographically sign the serialized data. Before deserialization, validate the cryptographic signature. Protect the cryptographic key from being disclosed, and design for key rotations.
 - Restrict deserialized types. Implement a custom <xref:System.Runtime.Serialization.SerializationBinder?displayProperty=nameWithType>. Before deserializing with <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter>, set the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Binder> property to an instance of your custom <xref:System.Runtime.Serialization.SerializationBinder>. In the overridden <xref:System.Runtime.Serialization.SerializationBinder.BindToType%2A> method, if the type is unexpected then throw an exception.
-- If you restrict deserialized types, you may want to disable this rule and enable rules [CA2301](ca2301-do-not-call-binaryformatter-deserialize-without-first-setting-binaryformatter-binder.md) and [CA2302](ca2302-ensure-binaryformatter-binder-is-set-before-calling-binaryformatter-deserialize.md). Enabling rules [CA2301](ca2301-do-not-call-binaryformatter-deserialize-without-first-setting-binaryformatter-binder.md) and [CA2302](ca2302-ensure-binaryformatter-binder-is-set-before-calling-binaryformatter-deserialize.md) will help ensure that the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Binder> property is always set before deserializing.
+- If you restrict deserialized types, you may want to disable this rule and enable rules [CA2301](ca2301-do-not-call-binaryformatter-deserialize-without-first-setting-binaryformatter-binder.md) and [CA2302](ca2302-ensure-binaryformatter-binder-is-set-before-calling-binaryformatter-deserialize.md). Rules [CA2301](ca2301-do-not-call-binaryformatter-deserialize-without-first-setting-binaryformatter-binder.md) and [CA2302](ca2302-ensure-binaryformatter-binder-is-set-before-calling-binaryformatter-deserialize.md) help to ensure that the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Binder> property is always set before deserializing.
 
 ## When to suppress warnings
 
-- It's safe to suppress a warning from this rule if you know the input is trusted. Consider that your application's trust boundary and data flows may change over time.
-- It's safe to suppress this warning if you've taken one of the precautions above.
+[!INCLUDE[insecure-deserializers-common-safe-to-suppress](includes/insecure-deserializers-common-safe-to-suppress-md.md)]
 
 ## Pseudo-code examples
 

docs/code-quality/ca2301-do-not-call-binaryformatter-deserialize-without-first-setting-binaryformatter-binder.md

@@ -35,17 +35,16 @@ This rule finds <xref:System.Runtime.Serialization.Formatters.Binary.BinaryForma
 - If possible, use a secure serializer instead, and **don't allow an attacker to specify an arbitrary type to deserialize**. Some safer serializers include:
   - <xref:System.Runtime.Serialization.DataContractSerializer?displayProperty=nameWithType>
   - <xref:System.Runtime.Serialization.Json.DataContractJsonSerializer?displayProperty=nameWithType>
-  - <xref:System.Web.Script.Serialization.JavaScriptSerializer?displayProperty=nameWithType> - Never use <xref:System.Web.Script.Serialization.SimpleTypeResolver?displayProperty=nameWithType>. If you must use a type resolver, you must restrict deserialized types to an expected list.
+  - <xref:System.Web.Script.Serialization.JavaScriptSerializer?displayProperty=nameWithType> - Never use <xref:System.Web.Script.Serialization.SimpleTypeResolver?displayProperty=nameWithType>. If you must use a type resolver, restrict deserialized types to an expected list.
   - <xref:System.Xml.Serialization.XmlSerializer?displayProperty=nameWithType>
-  - NewtonSoft Json.NET - Use TypeNameHandling.None. If you must use another value for TypeNameHandling, then you must restrict deserialized types to an expected list.
+  - NewtonSoft Json.NET - Use TypeNameHandling.None. If you must use another value for TypeNameHandling, restrict deserialized types to an expected list with a custom ISerializationBinder.
   - Protocol Buffers
-- Make the serialized data tamper proof. After serialization, cryptographically sign the serialized data. Before deserializing, validate the cryptographic signature. You must protect the cryptographic key from being disclosed, and should design for key rotations.
+- Make the serialized data tamper-proof. After serialization, cryptographically sign the serialized data. Before deserialization, validate the cryptographic signature. Protect the cryptographic key from being disclosed, and design for key rotations.
 - Restrict deserialized types. Implement a custom <xref:System.Runtime.Serialization.SerializationBinder?displayProperty=nameWithType>. Before deserializing with <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter>, set the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Binder> property to an instance of your custom <xref:System.Runtime.Serialization.SerializationBinder>. In the overridden <xref:System.Runtime.Serialization.SerializationBinder.BindToType%2A> method, if the type is unexpected then throw an exception.
 
 ## When to suppress warnings
 
-- It's safe to suppress a warning from this rule if you know the input is trusted. Consider that your application's trust boundary and data flows may change over time.
-- It's safe to suppress this warning if you've taken one of the precautions above.
+[!INCLUDE[insecure-deserializers-common-safe-to-suppress](includes/insecure-deserializers-common-safe-to-suppress-md.md)]
 
 ## Pseudo-code examples
 
@@ -114,6 +113,7 @@ End Class
 ```
 
 ### Solution
+
 ```csharp
 using System;
 using System.IO;
@@ -135,7 +135,7 @@ public class BookRecordSerializationBinder : SerializationBinder
         }
         else
         {
-            throw new ArgumentException("Unexpected type", "typeName");
+            throw new ArgumentException("Unexpected type", nameof(typeName));
         }
     }
 }
@@ -188,7 +188,7 @@ Public Class BookRecordSerializationBinder
         If typeName = "BinaryFormatterVB.BookRecord" Or typeName = "BinaryFormatterVB.AisleLocation" Then
             Return Nothing
         Else
-            Throw New ArgumentException("Unexpected type", "typeName")
+            Throw New ArgumentException("Unexpected type", NameOf(typeName))
         End If
     End Function
 End Class