Add documentation about the different scenarios this plugin has to support in the relevant areas of code or build scripts to serve as a reminder in the future.

Author: ivanz

Source/Machine.VSTestAdapter/Helpers/IsolatedAppDomainExecutionScope.cs

@@ -53,8 +53,11 @@ public T CreateInstance()
 
         private static AppDomain CreateAppDomain(string assemblyPath, string appName)
         {
-            // This is needed for the Visual Studio extension (.vsix), but not required for the nuget package, because
-            // the nuget package is injecting msbuild to copy the test adapter bits into the build output.
+            // This is needed in the following two scenarios, so that the target test dll and its dependencies are loaded correctly:
+            //
+            // 1. pre-.NET Standard (old) .csproj and Visual Studio IDE Test Explorer run
+            // 2. vstest.console.exe run against .dll which is not in the build output folder (e.g. packaged build artifact)
+            // 
             CopyRequiredRuntimeDependencies(new[] {
                 typeof(IsolatedAppDomainExecutionScope<>).Assembly,
                 typeof(Mono.Cecil.MemberReference).Assembly,

Source/Machine.VSTestAdapter/Machine.Specifications.Runner.VisualStudio.props

@@ -1,5 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project ToolsVersion="12.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+  <!-- 
+    The new dotnet tooling for the new .csproj format looks for test adapters in the build output directory 
+    and this msbuild script is ensuring we are copying everything needed.
+
+    It is ran automatically for us by simply being in the "build" folder in the nuget package.
+
+    MSBuildThisFileDirectory will be the full path to the relevant framework the build is running for.
+  -->
   <ItemGroup>
 
     <!-- .NET Framework only -->

Source/Machine.VSTestAdapter/Machine.VSTestAdapter.csproj

@@ -75,7 +75,7 @@
       <PackagePath>build\$(_TargetDotNet)\</PackagePath>
     </Content>
 
-    <!-- .NET Framework - new .csproj -->
+    <!-- .NET Framework - support for the new .csproj and dotnet test tooling -->
     <Content Include="Machine.Specifications.Runner.VisualStudio.props">
       <Pack>true</Pack>
       <PackagePath>build\$(_TargetDotNetFramework)\</PackagePath>
@@ -89,7 +89,7 @@
       <PackagePath>build\$(_TargetDotNetFramework)\</PackagePath>
     </Content>
 
-    <!-- .NET Framework - old .csproj -->
+    <!-- .NET Framework - support for the old .csproj and vstest.console/IDE tooling -->
     <Content Include="bin\$(Configuration)\$(_TargetDotNetFramework)\*.dll">
       <Pack>true</Pack>
       <PackagePath>tools\</PackagePath>