Merge branch 'gep13-feature/cake-buildGH-927' into develop

src/Cake.Common/Tools/Chocolatey/ChocolateyAliases.cs

@@ -15,7 +15,12 @@
 namespace Cake.Common.Tools.Chocolatey
 {
     /// <summary>
-    /// Contains functionality for working with Chocolatey.
+    /// <para>Contains functionality for working with <see href="https://github.com/chocolatey/choco">Chocolatey</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, Chocolatey will require to be installed on the machine where the build script
+    /// is being run.  See this <see href="https://github.com/chocolatey/choco/wiki/Installation">page</see> for details on how
+    /// Chocolatey can be installed.
+    /// </para>
     /// </summary>
     [CakeAliasCategory("Chocolatey")]
     public static class ChocolateyAliases

src/Cake.Common/Tools/DNU/DNUAliases.cs

@@ -2,6 +2,7 @@
 using Cake.Common.Tools.DNU.Build;
 using Cake.Common.Tools.DNU.Pack;
 using Cake.Common.Tools.DNU.Restore;
+using Cake.Common.Tools.DotNetCore;
 using Cake.Core;
 using Cake.Core.Annotations;
 using Cake.Core.IO;
@@ -10,6 +11,7 @@ namespace Cake.Common.Tools.DNU
 {
     /// <summary>
     /// Contains functionality for working with the DNU Utility.
+    /// <para>These aliases have been marked as Obsolete.  Use the <see cref="DotNetCoreAliases" /> instead.</para>
     /// </summary>
     [CakeAliasCategory("DNU")]
     public static class DNUAliases

src/Cake.Common/Tools/DotCover/DotCoverAliases.cs

@@ -8,7 +8,14 @@
 namespace Cake.Common.Tools.DotCover
 {
     /// <summary>
-    /// Contains functionality related to DotCover.
+    /// <para>Contains functionality related to <see href="https://www.jetbrains.com/dotcover/">DotCover</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the appropriate settings class:
+    /// <code>
+    /// #tool "nuget:?package=JetBrains.dotCover.CommandLineTools"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("DotCover")]
     public static class DotCoverAliases

src/Cake.Common/Tools/DotNetCore/DotNetCoreAliases.cs

@@ -13,7 +13,12 @@
 namespace Cake.Common.Tools.DotNetCore
 {
     /// <summary>
-    /// Contains functionality for working with the .NET Core CLI.
+    /// <para>Contains functionality related to <see href="https://github.com/dotnet/cli">.NET Core CLI</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, the .Net Core CLI tools will need to be installed on the machine where
+    /// the Cake script is being executed.  See this <see href="https://www.microsoft.com/net/core">page</see> for information
+    /// on how to install.
+    /// </para>
     /// </summary>
     [CakeAliasCategory("DotNetCore")]
     public static class DotNetCoreAliases

src/Cake.Common/Tools/DupFinder/DupFinderAliases.cs

@@ -9,7 +9,14 @@
 namespace Cake.Common.Tools.DupFinder
 {
     /// <summary>
-    ///  Contains functionality related to ReSharper's duplication finder
+    /// <para>Contains functionality related to ReSharper's <see href="https://www.jetbrains.com/help/resharper/2016.1/dupFinder.html">dupFinder</see> tool.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="DupFinderSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=JetBrains.ReSharper.CommandLineTools"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("ReSharper")]
     public static class DupFinderAliases

src/Cake.Common/Tools/Fixie/FixieAliases.cs

@@ -9,7 +9,14 @@
 namespace Cake.Common.Tools.Fixie
 {
     /// <summary>
-    /// Contains functionality related to running Fixie tests.
+    /// <para>Contains functionality related to running <see href="https://github.com/fixie/fixie">Fixie</see> tests.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="FixieSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=Fixie"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("Fixie")]
     public static class FixieAliases

src/Cake.Common/Tools/GitLink/GitLinkAliases.cs

@@ -6,7 +6,14 @@
 namespace Cake.Common.Tools.GitLink
 {
     /// <summary>
-    /// Contains functionality for working with GitLink.
+    /// <para>Contains functionality related to <see href="https://github.com/gittools/gitlink">GitLink</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="GitLinkSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=gitlink"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("GitTools")]
     public static class GitLinkAliases

src/Cake.Common/Tools/GitReleaseManager/GitReleaseManagerAliases.cs

@@ -11,7 +11,14 @@
 namespace Cake.Common.Tools.GitReleaseManager
 {
     /// <summary>
-    /// Contains functionality for working with GitReleaseManager.
+    /// <para>Contains functionality related to <see href="https://github.com/gittools/gitreleasemanager">GitReleaseManager</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the appropriate settings class:
+    /// <code>
+    /// #tool "nuget:?package=gitreleasemanager"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("GitReleaseManager")]
     public static class GitReleaseManagerAliases
@@ -249,7 +256,7 @@ public static void GitReleaseManagerPublish(this ICakeContext context, string us
             {
                 throw new ArgumentNullException("context");
             }
-            
+
             var publisher = new GitReleaseManagerPublisher(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools);
             publisher.Publish(userName, password, owner, repository, tagName, settings);
         }
@@ -305,7 +312,7 @@ public static void GitReleaseManagerExport(this ICakeContext context, string use
             {
                 throw new ArgumentNullException("context");
             }
-            
+
             var publisher = new GitReleaseManagerExporter(context.FileSystem, context.Environment, context.ProcessRunner, context.Tools);
             publisher.Export(userName, password, owner, repository, fileOutputPath, settings);
         }

src/Cake.Common/Tools/GitReleaseNotes/GitReleaseNotesAliases.cs

@@ -6,7 +6,14 @@
 namespace Cake.Common.Tools.GitReleaseNotes
 {
     /// <summary>
-    ///  Contains functionality related to GitReleaseNotes
+    /// <para>Contains functionality related to <see href="https://github.com/gittools/gitreleasenotes">GitReleaseNotes</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="GitReleaseNotesSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=GitReleaseNotes"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("GitReleaseNotes")]
     public static class GitReleaseNotesAliases

src/Cake.Common/Tools/GitVersion/GitVersionAliases.cs

@@ -5,9 +5,14 @@
 namespace Cake.Common.Tools.GitVersion
 {
     /// <summary>
-    /// Contains functionality related to GitVersion.
-    /// <see href="http://gitversion.readthedocs.org/en/latest/">GitVersion Documentation</see>
-    /// <see href="https://www.nuget.org/packages/GitVersion.CommandLine/">GitVersion NuGet Package</see>
+    /// <para>Contains functionality related to <see href="https://github.com/gittools/gitversion">GitVersion</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="GitVersionSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=GitVersion.CommandLine"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("GitVersion")]
     public static class GitVersionAliases

src/Cake.Common/Tools/ILMerge/ILMergeAliases.cs

@@ -7,9 +7,10 @@
 namespace Cake.Common.Tools.ILMerge
 {
     /// <summary>
-    /// <para>Contains functionality related to ILMerge.</para>
+    /// <para>Contains functionality related to <see href="http://research.microsoft.com/en-us/people/mbarnett/ILMerge.aspx">ILMerge</see>.</para>
     /// <para>
-    /// In order to use the commands for this alias, include the following in your build.cake file to download and install from NuGet.org, or specify the ToolPath within the ILMergeSettings class:
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="ILMergeSettings" /> class:
     /// <code>
     /// #tool "nuget:?package=ilmerge"
     /// </code>

src/Cake.Common/Tools/ILRepack/ILRepackAliases.cs

@@ -7,9 +7,10 @@
 namespace Cake.Common.Tools.ILRepack
 {
     /// <summary>
-    /// <para>Contains functionality related to ILRepack.</para>
+    /// <para>Contains functionality related to <see href="https://github.com/gluck/il-repack">ILRepack</see>.</para>
     /// <para>
-    /// In order to use the commands for this alias, include the following in your build.cake file to download and install from NuGet.org, or specify the ToolPath within the ILRepackSettings class:
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="ILRepackSettings" /> class:
     /// <code>
     /// #tool "nuget:?package=ILRepack"
     /// </code>

src/Cake.Common/Tools/InspectCode/InspectCodeAliases.cs

@@ -6,7 +6,14 @@
 namespace Cake.Common.Tools.InspectCode
 {
     /// <summary>
-    /// Contains functionality related to Resharper's code inspection.
+    /// <para>Contains functionality related to ReSharper's <see href="https://www.jetbrains.com/help/resharper/2016.1/InspectCode.html">InspectCode</see> tool.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="InspectCodeSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=JetBrains.ReSharper.CommandLineTools"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("ReSharper")]
     public static class InspectCodeAliases

src/Cake.Common/Tools/MSBuild/MSBuildAliases.cs

@@ -6,7 +6,11 @@
 namespace Cake.Common.Tools.MSBuild
 {
     /// <summary>
-    /// Contains functionality related to MSBuild.
+    /// <para>Contains functionality related to <see href="https://msdn.microsoft.com/en-us/library/dd393574.aspx">MSBuild</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, MSBuild will already have to be installed on the machine the Cake Script
+    /// is being executed.
+    /// </para>
     /// </summary>
     [CakeAliasCategory("MSBuild")]
     public static class MSBuildAliases

src/Cake.Common/Tools/MSTest/MSTestAliases.cs

@@ -9,7 +9,12 @@
 namespace Cake.Common.Tools.MSTest
 {
     /// <summary>
-    /// Contains functionality related to running MSTest unit tests.
+    /// <para>Contains functionality related to running <see href="https://msdn.microsoft.com/en-us/library/ms182486.aspx">MSTest</see> unit tests.</para>
+    /// <para>
+    /// In order to use the commands for this alias, MSTest will need to be installed on the machine where
+    /// the Cake script is being executed.  This is typically achieved by having either Visual Studio installed, or by
+    /// using the Micrsoft Build Tools, for example, for <see href="https://www.microsoft.com/en-us/download/details.aspx?id=48159">2015</see>.
+    /// </para>
     /// </summary>
     [CakeAliasCategory("MSTest")]
     public static class MSTestAliases

src/Cake.Common/Tools/NSIS/NSISAliases.cs

@@ -6,7 +6,12 @@
 namespace Cake.Common.Tools.NSIS
 {
     /// <summary>
-    /// Contains functionality related to running NSIS.
+    /// <para>Contains functionality related to <see href="http://nsis.sourceforge.net/Main_Page">NSIS</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, NSIS will need to be installed on the machine where
+    /// the Cake script is being executed.  See this <see href="http://nsis.sourceforge.net/Download">page</see> for information
+    /// on how to download/install.
+    /// </para>
     /// </summary>
     [CakeAliasCategory("NSIS")]
     // ReSharper disable once InconsistentNaming

src/Cake.Common/Tools/NUnit/NUnit3Aliases.cs

@@ -9,7 +9,14 @@
 namespace Cake.Common.Tools.NUnit
 {
     /// <summary>
-    /// Contains functionality related to running NUnit v2 and v3 unit tests.
+    /// <para>Contains functionality related to running <see href="https://github.com/nunit/nunit">NUnit</see> v2 and v3 unit tests.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="NUnit3Settings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=NUnit.ConsoleRunner"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("NUnit v3")]
     public static class NUnit3Aliases

src/Cake.Common/Tools/NUnit/NUnitAliases.cs

@@ -9,7 +9,14 @@
 namespace Cake.Common.Tools.NUnit
 {
     /// <summary>
-    /// Contains functionality related to running NUnit unit tests.
+    /// <para>Contains functionality related to running <see href="https://github.com/nunit/nunit">NUnit</see> tests.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="NUnitSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=NUnit.Runners&amp;version=2.6.4"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("NUnit")]
     public static class NUnitAliases
@@ -49,7 +56,7 @@ public static void NUnit(this ICakeContext context, string pattern)
         /// <example>
         /// <code>
         /// NUnit("./src/UnitTests/*.dll", new NUnitSettings {
-        ///     Timeout = 4000, 
+        ///     Timeout = 4000,
         ///     StopOnError = true
         ///     });
         /// </code>

src/Cake.Common/Tools/NuGet/NuGetAliases.cs

@@ -16,8 +16,12 @@
 namespace Cake.Common.Tools.NuGet
 {
     /// <summary>
-    /// Contains functionality for working with NuGet.
+    /// Contains functionality for working with <see href="https://www.nuget.org/">NuGet</see>.
     /// </summary>
+    /// <para>
+    /// Since Cake requires NuGet to be available very early in the build pipeline, we recommend that NuGet is made
+    /// available via the <see href="https://github.com/cake-build/resources">Cake BootStrapper</see>.
+    /// </para>
     [CakeAliasCategory("NuGet")]
     public static class NuGetAliases
     {
@@ -693,7 +697,7 @@ public static void NuGetInstallFromConfig(this ICakeContext context, FilePath pa
         /// <example>
         /// <code>
         /// var packageConfigs = GetFiles("./**/packages.config");
-        /// 
+        ///
         /// NuGetInstallFromConfig(packageConfigs);
         /// </code>
         /// </example>
@@ -744,7 +748,7 @@ public static void NuGetInstallFromConfig(this ICakeContext context, FilePath pa
         /// <example>
         /// <code>
         /// var packageConfigs = GetFiles("./**/packages.config");
-        /// 
+        ///
         /// NuGetInstallFromConfig(packageConfigs, new NuGetInstallSettings {
         ///     ExcludeVersion  = true,
         ///     OutputDirectory = "./tools"
@@ -894,7 +898,7 @@ public static void NuGetUpdate(this ICakeContext context, FilePath targetFile)
         /// <example>
         /// <code>
         /// var targets = GetFiles("./**/packages.config");
-        /// 
+        ///
         /// NuGetUpdate(targets);
         /// </code>
         /// </example>
@@ -944,7 +948,7 @@ public static void NuGetUpdate(this ICakeContext context, FilePath targetFile, N
         /// <example>
         /// <code>
         /// var targets = GetFiles("./**/packages.config");
-        /// 
+        ///
         /// NuGetUpdate(targets, new NuGetUpdateSettings {
         ///     Prerelease = true,
         /// });

src/Cake.Common/Tools/OctopusDeploy/OctopusDeployAliases.cs

@@ -5,7 +5,14 @@
 namespace Cake.Common.Tools.OctopusDeploy
 {
     /// <summary>
-    /// Contains functionality for working with Octopus Deploy.
+    /// <para>Contains functionality related to <see href="https://octopus.com/">Octopus Deploy</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the appropriate settings class:
+    /// <code>
+    /// #tool "nuget:?package=OctopusTools"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("Octopus Deploy")]
     public static class OctopusDeployAliases

src/Cake.Common/Tools/OpenCover/OpenCoverAliases.cs

@@ -6,7 +6,14 @@
 namespace Cake.Common.Tools.OpenCover
 {
     /// <summary>
-    /// Contains functionality related to OpenCover.
+    /// <para>Contains functionality related to <see href="https://github.com/opencover/opencover">OpenCover</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="OpenCoverSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=OpenCover"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("OpenCover")]
     public static class OpenCoverAliases

src/Cake.Common/Tools/ReportGenerator/ReportGeneratorAliases.cs

@@ -7,7 +7,14 @@
 namespace Cake.Common.Tools.ReportGenerator
 {
     /// <summary>
-    /// Contains functionality related to <see href="https://github.com/danielpalme/ReportGenerator">ReportGenerator</see>.
+    /// <para>Contains functionality related to <see href="https://github.com/danielpalme/ReportGenerator">ReportGenerator</see>.</para>
+    /// <para>
+    /// In order to use the commands for this alias, include the following in your build.cake file to download and
+    /// install from NuGet.org, or specify the ToolPath within the <see cref="ReportGeneratorSettings" /> class:
+    /// <code>
+    /// #tool "nuget:?package=ReportGenerator"
+    /// </code>
+    /// </para>
     /// </summary>
     [CakeAliasCategory("ReportGenerator")]
     public static class ReportGeneratorAliases