From b193bfc620f3f43bec529d7fc00ef9106a5a3ebb Mon Sep 17 00:00:00 2001 From: Ash Beeson Date: Sat, 19 Nov 2016 22:57:44 +0000 Subject: [PATCH] Complete Xml documentation, fixes #4 --- Cake.Stylecop/Cake.StyleCop.csproj | 2 ++ Cake.Stylecop/Cake.StyleCop.nuspec | 3 +- Cake.Stylecop/StyleCopHandlers.cs | 24 +++++++++++-- Cake.Stylecop/StyleCopReportSettings.cs | 6 ++++ Cake.Stylecop/StyleCopRunner.cs | 38 ++++++++++++++++++++- Cake.Stylecop/StyleCopSettings.cs | 6 ++++ Cake.Stylecop/StyleCopSettingsExtensions.cs | 3 ++ build.cake | 2 +- tools/packages.config | 2 +- 9 files changed, 79 insertions(+), 7 deletions(-) diff --git a/Cake.Stylecop/Cake.StyleCop.csproj b/Cake.Stylecop/Cake.StyleCop.csproj index 3887c1b..f0ce4cb 100644 --- a/Cake.Stylecop/Cake.StyleCop.csproj +++ b/Cake.Stylecop/Cake.StyleCop.csproj @@ -20,6 +20,7 @@ DEBUG;TRACE prompt 4 + bin\Debug\Cake.StyleCop.XML pdbonly @@ -28,6 +29,7 @@ TRACE prompt 4 + bin\Release\Cake.StyleCop.XML diff --git a/Cake.Stylecop/Cake.StyleCop.nuspec b/Cake.Stylecop/Cake.StyleCop.nuspec index 9f3f303..6ec55c9 100644 --- a/Cake.Stylecop/Cake.StyleCop.nuspec +++ b/Cake.Stylecop/Cake.StyleCop.nuspec @@ -16,10 +16,11 @@ - + + diff --git a/Cake.Stylecop/StyleCopHandlers.cs b/Cake.Stylecop/StyleCopHandlers.cs index 2a6e91f..b3a3726 100644 --- a/Cake.Stylecop/StyleCopHandlers.cs +++ b/Cake.Stylecop/StyleCopHandlers.cs @@ -3,20 +3,28 @@ using Cake.Core; using global::StyleCop; - - using StyleCop; - + + /// + /// Stylecop utility class. + /// public class StylecopHandlers { private readonly ICakeContext _context; private int _totalViolations; + /// + /// Creates a new instance. + /// + /// The context. public StylecopHandlers(ICakeContext context) { _context = context; } + /// + /// The total number of violations. + /// public int TotalViolations { get @@ -25,11 +33,21 @@ public int TotalViolations } } + /// + /// Called when Stylecop output has been generated. + /// + /// The sender. + /// The event args. public void OnOutputGenerated(object sender, OutputEventArgs args) { Cake.Common.Diagnostics.LoggingAliases.Information(_context, args.Output); } + /// + /// Called when Stylecop has encountered a rule violation. + /// + /// The sender. + /// The event args. public void ViolationEncountered(object sender, ViolationEventArgs args) { _totalViolations++; diff --git a/Cake.Stylecop/StyleCopReportSettings.cs b/Cake.Stylecop/StyleCopReportSettings.cs index cb3737a..49df65d 100644 --- a/Cake.Stylecop/StyleCopReportSettings.cs +++ b/Cake.Stylecop/StyleCopReportSettings.cs @@ -2,8 +2,14 @@ { using Cake.Core.IO; + /// + /// A utility class for configuring stylecop output. + /// public class StyleCopReportSettings { + /// + /// Creates a new instance of the StyleCopReportSettings class. + /// public StyleCopReportSettings() { ResultFiles = new FilePathCollection(new PathComparer(false)); diff --git a/Cake.Stylecop/StyleCopRunner.cs b/Cake.Stylecop/StyleCopRunner.cs index 3a3a325..3aed2a7 100644 --- a/Cake.Stylecop/StyleCopRunner.cs +++ b/Cake.Stylecop/StyleCopRunner.cs @@ -16,14 +16,33 @@ using global::StyleCop; + /// + /// A proxy onto the StyleCopSettings type. + /// + /// The settings. + /// The settings. public delegate StyleCopSettings SettingsDelegate(StyleCopSettings settings); + + /// + /// A proxy onto the StyleCopReportSettings type. + /// + /// The settings. + /// The settings. public delegate StyleCopReportSettings ReportSettingsDelegate(StyleCopReportSettings settings); + /// + /// The class that executes stylecop analysis. + /// public static class StyleCopRunner { private static StyleCopSettings settings; private const string FOLDER_PROJECT_TYPE_GUID = "{2150E333-8FDC-42A3-9474-1A3956D46DE8}"; + /// + /// Starts an analysis run. + /// + /// The cake context. + /// The stylecop setting to use during the analysis. public static void Execute(ICakeContext context, SettingsDelegate settingsDelegate) { settings = settingsDelegate(new StyleCopSettings()); @@ -112,11 +131,12 @@ public static void Execute(ICakeContext context, SettingsDelegate settingsDelega /// /// Transforms the outputted report using an XSL transform file. /// + /// The fully qualified path of the output html file. /// /// The fully-qualified path of the report to transform. /// /// The filePath for the xslt transform - /// + /// The cake context. private static void Transform(ICakeContext context, FilePath htmlFile, FilePath outputXmlFile, FilePath transformFile) { if (!context.FileExists(outputXmlFile)) @@ -141,6 +161,11 @@ private static void Transform(ICakeContext context, FilePath htmlFile, FilePath context.Log.Debug($"Stylecop: Finished transform {outputXmlFile.FullPath} to {htmlFile}"); } + /// + /// The Assembly Directory. + /// + /// Assembly to return the directory path for. + /// The assemblies directory path. public static string AssemblyDirectory(Assembly assembly) { var codeBase = assembly.CodeBase; @@ -148,6 +173,11 @@ public static string AssemblyDirectory(Assembly assembly) return Uri.UnescapeDataString(uri.Path); } + /// + /// Starts the report aggregation process. + /// + /// The cake context. + /// The settings to use during report aggregation. public static void Report(ICakeContext context, ReportSettingsDelegate settingsDelegate) { try @@ -178,6 +208,12 @@ public static void Report(ICakeContext context, ReportSettingsDelegate settingsD } } + /// + /// Merges two or more Stylecop report files into a single xml document. + /// + /// The cake context. + /// A collection of report files to merge. + /// The resultant Xml document. public static XDocument MergeResultFile(ICakeContext context, FilePathCollection resultFiles) { context.Log.Information($"Stylecop: Loading result xml file {resultFiles.First().FullPath}"); diff --git a/Cake.Stylecop/StyleCopSettings.cs b/Cake.Stylecop/StyleCopSettings.cs index 6483132..d6983cb 100644 --- a/Cake.Stylecop/StyleCopSettings.cs +++ b/Cake.Stylecop/StyleCopSettings.cs @@ -2,8 +2,14 @@ { using Cake.Core.IO; + /// + /// Contains configuration for a stylecop analysis execution. + /// public class StyleCopSettings { + /// + /// Creates a new instance of the StyleCopSettings class. + /// public StyleCopSettings() { Addins = new DirectoryPathCollection(new PathComparer(false)); diff --git a/Cake.Stylecop/StyleCopSettingsExtensions.cs b/Cake.Stylecop/StyleCopSettingsExtensions.cs index 848bade..c7997d7 100644 --- a/Cake.Stylecop/StyleCopSettingsExtensions.cs +++ b/Cake.Stylecop/StyleCopSettingsExtensions.cs @@ -4,6 +4,9 @@ namespace Cake.Stylecop using Cake.Core.IO; + /// + /// Extensions that enable a fluent interface onto the StyleCopSettings type. + /// public static class StyleCopSettingsExtensions { /// diff --git a/build.cake b/build.cake index 4a87bf0..a3efe92 100644 --- a/build.cake +++ b/build.cake @@ -97,7 +97,7 @@ const string Configuration = "Release"; .Does(() => { var nuGetPackSettings = new NuGetPackSettings { - Version = "1.1.1", + Version = "1.1.2", BasePath = "./Cake.StyleCop", OutputDirectory = nupkgDestDir }; diff --git a/tools/packages.config b/tools/packages.config index 94fad2b..85fc75c 100644 --- a/tools/packages.config +++ b/tools/packages.config @@ -1,4 +1,4 @@ - +