diff --git a/.editorconfig b/.editorconfig index 9f45a62f9..169bd28ea 100644 --- a/.editorconfig +++ b/.editorconfig @@ -515,22 +515,6 @@ dotnet_diagnostic.SA1604.severity = suggestion # The documentation for parameter '...' is missing dotnet_diagnostic.SA1611.severity = suggestion -# https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1614.md -# Element parameter documentation should have text -dotnet_diagnostic.SA1614.severity = suggestion - -# https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1615.md -# Element return value should be documented -dotnet_diagnostic.SA1615.severity = suggestion - -# https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1616.md -# Element return value documentation should have text -dotnet_diagnostic.SA1616.severity = suggestion - -# https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1617.md -# Void return value should not be documented -dotnet_diagnostic.SA1617.severity = suggestion - # https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/SA1633.md # The file header is missing or not located at the top of the file. dotnet_diagnostic.SA1633.severity = suggestion diff --git a/src/Microsoft.ComponentDetection.Common/DockerReference/DockerRegex.cs b/src/Microsoft.ComponentDetection.Common/DockerReference/DockerRegex.cs index 1d51c6251..93d2a7c6a 100644 --- a/src/Microsoft.ComponentDetection.Common/DockerReference/DockerRegex.cs +++ b/src/Microsoft.ComponentDetection.Common/DockerReference/DockerRegex.cs @@ -5,49 +5,61 @@ namespace Microsoft.ComponentDetection.Common { public class DockerRegex { - /** - * expression defines a full expression, where each regular expression must follow the previous. - */ + /// + /// expression defines a full expression, where each regular expression must follow the previous. + /// + /// list of Regular expressions. + /// full Regex expression from the given list. public static Regex Expression(params Regex[] regexps) { return new Regex(string.Join(string.Empty, regexps.Select(re => re.ToString()))); } - /** - * group wraps the regexp in a non-capturing group. - */ + /// + /// group wraps the regexp in a non-capturing group. + /// + /// list of Regular expressions. + /// of the non-capturing group. public static Regex Group(params Regex[] regexps) { return new Regex($"(?:{Expression(regexps).ToString()})"); } - /** - * repeated wraps the regexp in a non-capturing group to get one or more matches. - */ + /// + /// repeated wraps the regexp in a non-capturing group to get one or more matches. + /// + /// list of Regular expressions. + /// The wrapped . public static Regex Optional(params Regex[] regexps) { return new Regex($"{Group(regexps).ToString()}?"); } - /** - * repeated wraps the regexp in a non-capturing group to get one or more matches. - */ + /// + /// repeated wraps the regexp in a non-capturing group to get one or more matches. + /// + /// list of Regular expressions. + /// The wrapped . public static Regex Repeated(params Regex[] regexps) { return new Regex($"{Group(regexps).ToString()}+"); } - /** - * anchored anchors the regular expression by adding start and end delimiters. - */ + /// + /// anchored anchors the regular expression by adding start and end delimiters. + /// + /// list of Regular expressions. + /// The anchored . public static Regex Anchored(params Regex[] regexps) { return new Regex($"^{Expression(regexps).ToString()}$"); } - /** - * capture wraps the expression in a capturing group. - */ + /// + /// capture wraps the expression in a capturing group. + /// + /// list of Regular expressions. + /// The captured . public static Regex Capture(params Regex[] regexps) { return new Regex($"({Expression(regexps).ToString()})"); diff --git a/src/Microsoft.ComponentDetection.Common/FastDirectoryWalkerFactory.cs b/src/Microsoft.ComponentDetection.Common/FastDirectoryWalkerFactory.cs index aefcb97b0..3a08ca3df 100644 --- a/src/Microsoft.ComponentDetection.Common/FastDirectoryWalkerFactory.cs +++ b/src/Microsoft.ComponentDetection.Common/FastDirectoryWalkerFactory.cs @@ -200,7 +200,7 @@ public IObservable GetDirectoryScanner(DirectoryInfo root, Concu /// Initialized an observable file enumerator. /// /// Root directory to scan. - /// + /// predicate for excluding directories. /// Number of observers that need to subscribe before the observable connects and starts enumerating. /// Pattern used to filter files. public void Initialize(DirectoryInfo root, ExcludeDirectoryPredicate directoryExclusionPredicate, int minimumConnectionCount, IEnumerable filePatterns = null) diff --git a/src/Microsoft.ComponentDetection.Common/PathUtilityService.cs b/src/Microsoft.ComponentDetection.Common/PathUtilityService.cs index cda65a524..fde74c778 100644 --- a/src/Microsoft.ComponentDetection.Common/PathUtilityService.cs +++ b/src/Microsoft.ComponentDetection.Common/PathUtilityService.cs @@ -22,9 +22,9 @@ public class PathUtilityService : IPathUtilityService /// Note: You may pass IntPtr.Zero to the output parameter. You MUST then free the IntPtr that RealPathLinux returns /// using FreeMemoryLinux otherwise things will get very leaky. /// - /// - /// - /// + /// The path to resolve. + /// The pointer output. + /// A pointer to the absolute path of a file. [DllImport("libc", EntryPoint = "realpath")] public static extern IntPtr RealPathLinux([MarshalAs(UnmanagedType.LPStr)] string path, IntPtr output); @@ -33,7 +33,7 @@ public class PathUtilityService : IPathUtilityService /// However, beware.... Improper usage of this function will cause segfaults and other nasty double-free errors. /// THIS WILL CRASH THE CLR IF YOU USE IT WRONG. /// - /// + /// Pointer to the memory space to free. [DllImport("libc", EntryPoint = "free")] public static extern void FreeMemoryLinux([In] IntPtr toFree); diff --git a/src/Microsoft.ComponentDetection.Common/Telemetry/TelemetryRelay.cs b/src/Microsoft.ComponentDetection.Common/Telemetry/TelemetryRelay.cs index 3e4176420..885cf704f 100644 --- a/src/Microsoft.ComponentDetection.Common/Telemetry/TelemetryRelay.cs +++ b/src/Microsoft.ComponentDetection.Common/Telemetry/TelemetryRelay.cs @@ -42,7 +42,7 @@ public static TelemetryRelay Instance /// /// Post a given telemetry record to all telemetry services. /// - /// + /// Record to post. public void PostTelemetryRecord(IDetectionTelemetryRecord record) { foreach (var service in TelemetryServices) diff --git a/src/Microsoft.ComponentDetection.Contracts/FileComponentDetector.cs b/src/Microsoft.ComponentDetection.Contracts/FileComponentDetector.cs index 5e3ce989a..9ad332a44 100644 --- a/src/Microsoft.ComponentDetection.Contracts/FileComponentDetector.cs +++ b/src/Microsoft.ComponentDetection.Contracts/FileComponentDetector.cs @@ -70,7 +70,7 @@ private Task ScanDirectoryAsync(ScanRequest reques /// /// The directory to search. /// The exclusion predicate function. - /// + /// Awaitable task with enumerable streams for the declared detector. protected Task> GetFileStreamsAsync(DirectoryInfo sourceDirectory, ExcludeDirectoryPredicate exclusionPredicate) { return Task.FromResult(this.ComponentStreamEnumerableFactory.GetComponentStreams(sourceDirectory, this.SearchPatterns, exclusionPredicate)); diff --git a/src/Microsoft.ComponentDetection.Contracts/IComponentDetector.cs b/src/Microsoft.ComponentDetection.Contracts/IComponentDetector.cs index 06691f648..770efef84 100644 --- a/src/Microsoft.ComponentDetection.Contracts/IComponentDetector.cs +++ b/src/Microsoft.ComponentDetection.Contracts/IComponentDetector.cs @@ -33,7 +33,7 @@ public interface IComponentDetector /// /// Run the detector and return the result set of components found. /// - /// + /// Awaitable task with result of components found. Task ExecuteDetectorAsync(ScanRequest request); /// diff --git a/src/Microsoft.ComponentDetection.Contracts/IComponentRecorder.cs b/src/Microsoft.ComponentDetection.Contracts/IComponentRecorder.cs index 60b547be5..667c79c04 100644 --- a/src/Microsoft.ComponentDetection.Contracts/IComponentRecorder.cs +++ b/src/Microsoft.ComponentDetection.Contracts/IComponentRecorder.cs @@ -27,7 +27,6 @@ public interface ISingleFileComponentRecorder /// Id of the parent component. /// Boolean value indicating whether or not a component is a development-time dependency. Null implies that the value is unknown. /// Enum value indicating scope of the component. - /// DetectedComponent added or updated. void RegisterUsage( DetectedComponent detectedComponent, bool isExplicitReferencedDependency = false, @@ -90,6 +89,7 @@ public interface IDependencyGraph /// Null can be returned if a detector doesn't have the scope infromation. /// /// The componentId to check. + /// DependencyScope for the given componentId. DependencyScope? GetDependencyScope(string componentId); /// diff --git a/src/Microsoft.ComponentDetection.Contracts/IComponentStreamEnumerableFactory.cs b/src/Microsoft.ComponentDetection.Contracts/IComponentStreamEnumerableFactory.cs index c6e0d1f80..0450226ac 100644 --- a/src/Microsoft.ComponentDetection.Contracts/IComponentStreamEnumerableFactory.cs +++ b/src/Microsoft.ComponentDetection.Contracts/IComponentStreamEnumerableFactory.cs @@ -14,7 +14,7 @@ public interface IComponentStreamEnumerableFactory /// The patterns to use in the search. /// Predicate which indicates which directories should be excluded. /// Indicates whether the streams should enumerate files from sub directories. - /// + /// Enumerable of files that matched the given search pattern and directory exclusion predicate. IEnumerable GetComponentStreams(DirectoryInfo directory, IEnumerable searchPatterns, ExcludeDirectoryPredicate directoryExclusionPredicate, bool recursivelyScanDirectories = true); /// @@ -25,7 +25,7 @@ public interface IComponentStreamEnumerableFactory /// Predicate which indicates what files should be included. /// Predicate which indicates which directories should be excluded. /// Indicates whether the streams should enumerate files from sub directories. - /// + /// Enumerable of files that matched the given file matching predicate and directory exclusion predicate. IEnumerable GetComponentStreams(DirectoryInfo directory, Func fileMatchingPredicate, ExcludeDirectoryPredicate directoryExclusionPredicate, bool recursivelyScanDirectories = true); } } diff --git a/src/Microsoft.ComponentDetection.Contracts/IPathUtilityService.cs b/src/Microsoft.ComponentDetection.Contracts/IPathUtilityService.cs index 5dc692032..32a0f68a6 100644 --- a/src/Microsoft.ComponentDetection.Contracts/IPathUtilityService.cs +++ b/src/Microsoft.ComponentDetection.Contracts/IPathUtilityService.cs @@ -1,4 +1,4 @@ -namespace Microsoft.ComponentDetection.Contracts +namespace Microsoft.ComponentDetection.Contracts { /// /// Wraps some common folder operations, shared across command line app and service. @@ -10,16 +10,16 @@ public interface IPathUtilityService /// /// Given a path, resolve the underlying path, traversing any symlinks (man 2 lstat :D ). /// - /// - /// + /// Path that needs to be resolved. + /// Returns a string of the underlying path. string ResolvePhysicalPath(string path); /// /// Returns true when the below file path exists under the above file path. /// - /// - /// - /// + /// The top file path. + /// The file path to find within the top file path. + /// Return a bool. True, if below file path is found under above file path, otherwise false. bool IsFileBelowAnother(string aboveFilePath, string belowFilePath); /// @@ -27,7 +27,7 @@ public interface IPathUtilityService /// /// Search pattern. /// File name without directory. - /// + /// Returns true if file name matches a pattern, otherwise false. bool MatchesPattern(string searchPattern, string fileName); } } diff --git a/src/Microsoft.ComponentDetection.Detectors/linux/LinuxContainerDetector.cs b/src/Microsoft.ComponentDetection.Detectors/linux/LinuxContainerDetector.cs index 86fb7d402..2d727e6b8 100644 --- a/src/Microsoft.ComponentDetection.Detectors/linux/LinuxContainerDetector.cs +++ b/src/Microsoft.ComponentDetection.Detectors/linux/LinuxContainerDetector.cs @@ -83,7 +83,7 @@ public async Task ExecuteDetectorAsync(ScanRequest /// Extracts and returns the timeout defined by the user, or a default value if one is not provided. /// /// The arguments provided by the user. - /// + /// Time interval repesenting the timeout defined by the user, or a default value if one is not provided. private static TimeSpan GetTimeout(IDictionary detectorArgs) { if (detectorArgs == null || !detectorArgs.TryGetValue("Linux.ScanningTimeoutSec", out var timeout)) diff --git a/src/Microsoft.ComponentDetection.Detectors/nuget/NuGetComponentDetector.cs b/src/Microsoft.ComponentDetection.Detectors/nuget/NuGetComponentDetector.cs index 10cd87105..cd99af643 100644 --- a/src/Microsoft.ComponentDetection.Detectors/nuget/NuGetComponentDetector.cs +++ b/src/Microsoft.ComponentDetection.Detectors/nuget/NuGetComponentDetector.cs @@ -222,8 +222,8 @@ private IList GetRepositoryPathsFromNugetConfig(IComponentStream /// /// Checks to make sure a path is valid (does not have to exist). /// - /// - /// + /// The path to validate. + /// True if path is valid, otherwise it retuns false. private bool IsValidPath(string potentialPath) { FileInfo fileInfo = null; diff --git a/src/Microsoft.ComponentDetection.Detectors/pip/PipDependencySpecification.cs b/src/Microsoft.ComponentDetection.Detectors/pip/PipDependencySpecification.cs index 63c0c297c..450afe891 100644 --- a/src/Microsoft.ComponentDetection.Detectors/pip/PipDependencySpecification.cs +++ b/src/Microsoft.ComponentDetection.Detectors/pip/PipDependencySpecification.cs @@ -55,7 +55,7 @@ public class PipDependencySpecification /// /// Whether or not the package is safe to resolve based on the packagesToIgnore. /// - /// + /// True if the package is unsafe, otherwise false. public bool PackageIsUnsafe() { return PackagesToIgnore.Contains(this.Name); diff --git a/src/Microsoft.ComponentDetection.Detectors/pip/PythonVersionUtilities.cs b/src/Microsoft.ComponentDetection.Detectors/pip/PythonVersionUtilities.cs index e3c4ebfc7..b01fcbad6 100644 --- a/src/Microsoft.ComponentDetection.Detectors/pip/PythonVersionUtilities.cs +++ b/src/Microsoft.ComponentDetection.Detectors/pip/PythonVersionUtilities.cs @@ -11,7 +11,7 @@ public static class PythonVersionUtilities /// /// Version. /// Version specifications. - /// + /// True if the version is valid for all specs, otherwise false. /// The version or any of the specs are an invalid python version. public static bool VersionValidForSpec(string version, IList specs) { diff --git a/src/Microsoft.ComponentDetection.Detectors/rust/RustCrateUtilities.cs b/src/Microsoft.ComponentDetection.Detectors/rust/RustCrateUtilities.cs index c759813d5..a501061f7 100644 --- a/src/Microsoft.ComponentDetection.Detectors/rust/RustCrateUtilities.cs +++ b/src/Microsoft.ComponentDetection.Detectors/rust/RustCrateUtilities.cs @@ -225,7 +225,7 @@ public static CargoDependencyData ExtractRootDependencyAndWorkspaceSpecification /// The FileInfo for the cargo.lock file found in the root directory. /// A list of relative folder paths to include in search. /// A list of relative folder paths to exclude from search. - /// + /// Returns predicate which will be used to exclude directories. public static ExcludeDirectoryPredicate BuildExcludeDirectoryPredicateFromWorkspaces(FileInfo rootLockFileInfo, HashSet definedWorkspaces, HashSet definedExclusions) { var workspaceGlobs = BuildGlobMatchingFromWorkspaces(rootLockFileInfo, definedWorkspaces); @@ -314,7 +314,7 @@ private static void GenerateDependencies(TomlTable cargoToml, IList /// The FileInfo for the cargo.lock file found in the root directory. /// A list of relative folder paths to include in search. - /// + /// Dictionary with worspace paths and their corresponding Globs. private static Dictionary BuildGlobMatchingFromWorkspaces(FileInfo rootLockFileInfo, HashSet definedWorkspaces) { var directoryGlobs = new Dictionary diff --git a/src/Microsoft.ComponentDetection.Detectors/yarn/Parsers/YarnBlockFile.cs b/src/Microsoft.ComponentDetection.Detectors/yarn/Parsers/YarnBlockFile.cs index ac37316e5..e04468109 100644 --- a/src/Microsoft.ComponentDetection.Detectors/yarn/Parsers/YarnBlockFile.cs +++ b/src/Microsoft.ComponentDetection.Detectors/yarn/Parsers/YarnBlockFile.cs @@ -150,8 +150,8 @@ private void ReadVersionHeader() /// /// Parses a block and its sub-blocks into . /// - /// - /// + /// Level to get block from in YarnBlock file. + /// Yarnblock gotten from the parsed block. private YarnBlock ParseBlock(int level = 0) { var currentLevelDelimiter = " "; @@ -204,7 +204,7 @@ private YarnBlock ParseBlock(int level = 0) /// /// Increments the internal pointer so that it is at the next block. /// - /// + /// True if the pointer was succesfully incremented. private bool ReadToNextMajorBlock() { string line; @@ -234,7 +234,7 @@ private bool IncrementIndex() /// /// Checks to see if any lines are left in the file contents. /// - /// + /// True if there are any lines left in the file. private bool Peek() { if (this.fileLineIndex >= this.fileLines.Count) diff --git a/src/Microsoft.ComponentDetection.Detectors/yarn/YarnLockComponentDetector.cs b/src/Microsoft.ComponentDetection.Detectors/yarn/YarnLockComponentDetector.cs index 9652e3c73..ef2f36a06 100644 --- a/src/Microsoft.ComponentDetection.Detectors/yarn/YarnLockComponentDetector.cs +++ b/src/Microsoft.ComponentDetection.Detectors/yarn/YarnLockComponentDetector.cs @@ -170,7 +170,7 @@ private void ParseTreeWithAssignedRoot(YarnEntry root, DictionaryThe file location of the yarn.lock file. /// All the yarn entries that we know about. /// The output yarnRoots that we care about using as starting points. - /// + /// False if no package.json file was found at location, otherwise it returns true. private bool TryReadPeerPackageJsonRequestsAsYarnEntries(string location, Dictionary yarnEntries, out List yarnRoots) { yarnRoots = new List();