Add documentation and comments to explain what Microsoft.DotNet.GlobalTools.Sdk is used for

modules/BundledPackages/BundledPackages.proj

@@ -15,6 +15,11 @@
       RemoveProperties="PublishDir" />
 
     <PropertyGroup>
+      <!--
+        This is a workaround for https://github.com/Microsoft/msbuild/issues/2914.
+        Currently, the only way to configure the NuGetSdkResolver is with NuGet.config, which is not generally used in aspnet org projects.
+        This project is restored so that it pre-populates the NuGet cache with SDK packages.
+      -->
       <BundledPackageRestorerContent>
 <![CDATA[
 <Project Sdk="Microsoft.NET.Sdk">

modules/BundledPackages/module.targets

@@ -3,6 +3,10 @@
     <PrepareDependsOn>PreinstallBundledPackages;$(PrepareDependsOn)</PrepareDependsOn>
   </PropertyGroup>
 
+  <!--
+    This is a workaround for https://github.com/Microsoft/msbuild/issues/2914.
+    This pre-populates the NuGet cache with bundled packages.
+  -->
   <Target Name="PreinstallBundledPackages">
     <MSBuild Targets="Restore"
       Projects="$(MSBuildThisFileDirectory)BundledPackageRestorer.csproj"

src/Microsoft.DotNet.GlobalTools.Sdk/Microsoft.DotNet.GlobalTools.Sdk.nuspec

@@ -8,6 +8,7 @@
     <description>Provides additional support to .NET Core teams producing global CLI tools. This package is only intended for internal Microsoft use.</description>
     <copyright>$copyright$</copyright>
     <packageTypes>
+      <!-- This project needs to be MSBuildSdk because its targets need to influence the way /t:Restore works -->
       <packageType name="MSBuildSdk" />
     </packageTypes>
   </metadata>

src/Microsoft.DotNet.GlobalTools.Sdk/README.md

@@ -0,0 +1,43 @@
+Microsoft.DotNet.GlobalTools.Sdk
+================================
+
+Provides additional support to .NET Core teams producing global CLI tools. This package is only intended for internal Microsoft use.
+
+## Usage
+Projects that need to bundle and sign the global CLI tool shim should add this to their .csproj file. This will include files in the .nupkg.
+
+```xml
+<!-- In MyTool.csproj -->
+<Project>
+  <Sdk Name="Microsoft.NET.Sdk" />
+  <Sdk Name="Microsoft.DotNet.GlobalTools.Sdk" />
+
+  <PropertyGroup>
+    <PackAsTool>true</PackAsTool>
+    <GenerateToolShims>true</GenerateToolShims>
+  </PropertyGroup>
+</Project>
+```
+
+```js
+// in global.json
+{
+    "msbuild-sdks": {
+        "Microsoft.DotNet.GlobalTools.Sdk": "2.1.0-rtm-12345"
+    }
+}
+```
+
+### Additional options
+
+#### `GenerateToolShims` (property)
+
+A boolean flag. When `true`, tool shims will be generated for each RID listed in `GeneratedShimRuntimeIdentifiers` and included in the .nupkg.
+
+Default value = `false`
+
+#### `GeneratedShimRuntimeIdentifiers` (property)
+
+A semi-colon separate list of RIDs for which to generate and pack the shim.
+
+Default value = `win-x86;win-x64;osx-x64`