From b63c84fa74531b167faf1cbfaa59b2bf8014005a Mon Sep 17 00:00:00 2001 From: Thomas Shephard Date: Tue, 22 Oct 2024 21:10:45 +0100 Subject: [PATCH] docs: add XML documentation comments to public API (#93) --- src/CoverageChecker/CoverageAnalyser.cs | 21 +++++++++++++ src/CoverageChecker/CoverageFormat.cs | 3 ++ src/CoverageChecker/CoverageType.cs | 3 ++ src/CoverageChecker/Exceptions.cs | 12 +++++++ src/CoverageChecker/Results/Coverage.cs | 18 +++++++++++ src/CoverageChecker/Results/FileCoverage.cs | 33 +++++++++++++++++++ src/CoverageChecker/Results/LineCoverage.cs | 35 +++++++++++++++++++++ 7 files changed, 125 insertions(+) diff --git a/src/CoverageChecker/CoverageAnalyser.cs b/src/CoverageChecker/CoverageAnalyser.cs index be33034..dfdb532 100644 --- a/src/CoverageChecker/CoverageAnalyser.cs +++ b/src/CoverageChecker/CoverageAnalyser.cs @@ -4,13 +4,29 @@ namespace CoverageChecker; +/// +/// Analyses coverage information +/// public class CoverageAnalyser { private readonly CoverageFormat _coverageFormat; private readonly string _directory; private readonly string[] _globPatterns; + /// + /// Initializes a new instance of the class with a single glob pattern. + /// + /// The format of the coverage file. + /// The directory to search for coverage files within. + /// The glob pattern to use to search for coverage files. public CoverageAnalyser(CoverageFormat coverageFormat, string directory, string globPattern) : this(coverageFormat, directory, [globPattern]) { } + /// + /// Initializes a new instance of the class with multiple glob patterns. + /// + /// The format of the coverage file. + /// The directory to search for coverage files within. + /// The glob patterns to use to search for coverage files. + /// Thrown when no glob patterns are provided. public CoverageAnalyser(CoverageFormat coverageFormat, string directory, IEnumerable globPatterns) { globPatterns = globPatterns.ToArray(); @@ -23,6 +39,11 @@ public CoverageAnalyser(CoverageFormat coverageFormat, string directory, IEnumer _globPatterns = globPatterns.ToArray(); } + /// + /// Analyses the coverage information from the given glob patterns in the specified directory. + /// + /// The coverage information. + /// Thrown when no coverage files are found. public Coverage AnalyseCoverage() { string[] filePaths = GlobUtils.GetFilePathsFromGlobPatterns(_directory, _globPatterns).ToArray(); diff --git a/src/CoverageChecker/CoverageFormat.cs b/src/CoverageChecker/CoverageFormat.cs index e263b02..0406b36 100644 --- a/src/CoverageChecker/CoverageFormat.cs +++ b/src/CoverageChecker/CoverageFormat.cs @@ -1,5 +1,8 @@ namespace CoverageChecker; +/// +/// The format of the coverage report. +/// public enum CoverageFormat { Cobertura, SonarQube diff --git a/src/CoverageChecker/CoverageType.cs b/src/CoverageChecker/CoverageType.cs index c4f0e40..55afa64 100644 --- a/src/CoverageChecker/CoverageType.cs +++ b/src/CoverageChecker/CoverageType.cs @@ -1,5 +1,8 @@ namespace CoverageChecker; +/// +/// The type of code coverage to calculate. +/// public enum CoverageType { Line, Branch diff --git a/src/CoverageChecker/Exceptions.cs b/src/CoverageChecker/Exceptions.cs index 9679fd1..3c92918 100644 --- a/src/CoverageChecker/Exceptions.cs +++ b/src/CoverageChecker/Exceptions.cs @@ -1,19 +1,31 @@ namespace CoverageChecker; +/// +/// Base class for all custom exceptions thrown by this package. +/// public abstract class CoverageException : Exception { protected CoverageException() { } protected CoverageException(string message) : base(message) { } protected CoverageException(string message, Exception innerException) : base(message, innerException) { } } +/// +/// Thrown when no coverage files are found during analysis. +/// public class NoCoverageFilesFoundException : CoverageException { internal NoCoverageFilesFoundException() { } } +/// +/// Thrown when a coverage calculation cannot be performed. +/// public class CoverageCalculationException : CoverageException { internal CoverageCalculationException(string message) : base(message) { } } +/// +/// Thrown when a coverage file cannot be parsed. +/// public class CoverageParseException : CoverageException { internal CoverageParseException(string message) : base(message) { } internal CoverageParseException(string message, Exception innerException) : base(message, innerException) { } diff --git a/src/CoverageChecker/Results/Coverage.cs b/src/CoverageChecker/Results/Coverage.cs index a372c11..2874e94 100644 --- a/src/CoverageChecker/Results/Coverage.cs +++ b/src/CoverageChecker/Results/Coverage.cs @@ -2,7 +2,13 @@ namespace CoverageChecker.Results; +/// +/// Represents coverage information for a collection of files. +/// public class Coverage { + /// + /// The files that coverage information has been obtained for. + /// public IReadOnlyList Files => _files.AsReadOnly(); private readonly List _files = []; @@ -25,10 +31,22 @@ internal FileCoverage GetOrCreateFile(string filePath, string? packageName = nul return file; } + /// + /// Calculates the coverage for all files. + /// + /// The type of coverage to calculate. Defaults to . + /// The coverage for all files. public double CalculateOverallCoverage(CoverageType coverageType = CoverageType.Line) { return _files.CalculateCoverage(coverageType); } + /// + /// Calculates the coverage for all files that are part of the specified package. + /// + /// The name of the package to filter by. + /// The type of coverage to calculate. Defaults to . + /// The coverage for all files that are part of the specified package. + /// Thrown when no files are found that are part of the specified package. public double CalculatePackageCoverage(string packageName, CoverageType coverageType = CoverageType.Line) { FileCoverage[] filteredFiles = _files.Where(file => file.PackageName == packageName) .ToArray(); diff --git a/src/CoverageChecker/Results/FileCoverage.cs b/src/CoverageChecker/Results/FileCoverage.cs index 2a8bac7..7275b6f 100644 --- a/src/CoverageChecker/Results/FileCoverage.cs +++ b/src/CoverageChecker/Results/FileCoverage.cs @@ -2,9 +2,22 @@ namespace CoverageChecker.Results; +/// +/// Represents coverage information for a single file. +/// public class FileCoverage { + /// + /// The path of the file. + /// public string Path { get; } + /// + /// The name of the package the file is part of. + /// If null, the file is not part of a package. + /// public string? PackageName { get; } + /// + /// The lines within the file. + /// public IReadOnlyList Lines => _lines.AsReadOnly(); private readonly List _lines = []; @@ -28,10 +41,22 @@ internal void AddLine(int lineNumber, bool isCovered, int? branches = null, int? } } + /// + /// Calculates the coverage for the file. + /// + /// The type of coverage to calculate. Defaults to . + /// The coverage for the file. public double CalculateFileCoverage(CoverageType coverageType = CoverageType.Line) { return _lines.CalculateCoverage(coverageType); } + /// + /// Calculates the coverage for all lines that are part of the specified class. + /// + /// The name of the class to filter by. + /// The type of coverage to calculate. Defaults to . + /// The coverage for all lines that are part of the specified class. + /// Thrown when no lines are found that are part of the specified class. public double CalculateClassCoverage(string className, CoverageType coverageType = CoverageType.Line) { LineCoverage[] filteredLines = _lines.Where(line => line.ClassName == className) .ToArray(); @@ -42,6 +67,14 @@ public double CalculateClassCoverage(string className, CoverageType coverageType return filteredLines.CalculateCoverage(coverageType); } + /// + /// Calculates the coverage for all lines that are part of the specified method. + /// + /// The name of the method to filter by. + /// Optionally, the signature of the method to filter by. If null, only the method name is checked. + /// The type of coverage to calculate. Defaults to . + /// The coverage for all lines that are part of the specified method. + /// Thrown when no lines are found that are part of the specified method. public double CalculateMethodCoverage(string methodName, string? methodSignature = null, CoverageType coverageType = CoverageType.Line) { LineCoverage[] filteredLines = _lines.Where(line => { // If the method signature is null, only the method name is checked diff --git a/src/CoverageChecker/Results/LineCoverage.cs b/src/CoverageChecker/Results/LineCoverage.cs index 92d9c0f..7c673c3 100644 --- a/src/CoverageChecker/Results/LineCoverage.cs +++ b/src/CoverageChecker/Results/LineCoverage.cs @@ -2,13 +2,43 @@ namespace CoverageChecker.Results; +/// +/// Represents coverage information for a single line within a file. +/// public class LineCoverage { + /// + /// The line number. + /// public int LineNumber { get; } + /// + /// Whether the line is covered. + /// If true, the line has been covered, otherwise, false. + /// public bool IsCovered { get; private set; } + /// + /// The number of branches in the line. + /// If null, the line does not have any branches. + /// public int? Branches { get; private set; } + /// + /// The number of covered branches in the line. + /// If null, the line does not have any branches. + /// public int? CoveredBranches { get; private set; } + /// + /// The name of the class the line is part of. + /// If null, the line is not part of a class. + /// public string? ClassName { get; } + /// + /// The name of the method the line is part of. + /// If null, the line is not part of a method. + /// public string? MethodName { get; } + /// + /// The method signature of the method the line is part of. + /// If null, the line is not part of a method or the method does not have a method signature. + /// public string? MethodSignature { get; } internal LineCoverage(int lineNumber, bool isCovered, int? branches = null, int? coveredBranches = null, string? className = null, string? methodName = null, string? methodSignature = null) { @@ -34,6 +64,11 @@ internal LineCoverage(int lineNumber, bool isCovered, int? branches = null, int? MethodSignature = methodSignature; } + /// + /// Calculates the coverage for this line. + /// + /// The type of coverage to calculate. Defaults to . + /// The coverage for this line. public double CalculateLineCoverage(CoverageType coverageType = CoverageType.Line) { LineCoverage[] lines = [this];