Analyzer Warnings SA-1614, SA-1615, SA-1616, SA-1617

.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

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.
- */
+        /// <summary>
+        /// expression defines a full expression, where each regular expression must follow the previous.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> full Regex expression <see cref="Regex"/> from the given list. </returns>
         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.
-         */
+        /// <summary>
+        /// group wraps the regexp in a non-capturing group.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> <see cref="Regex"/> of the non-capturing group. </returns>
         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.
-         */
+        /// <summary>
+        /// repeated wraps the regexp in a non-capturing group to get one or more matches.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> The wrapped <see cref="Regex"/>. </returns>
         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.
-         */
+        /// <summary>
+        /// repeated wraps the regexp in a non-capturing group to get one or more matches.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> The wrapped <see cref="Regex"/>. </returns>
         public static Regex Repeated(params Regex[] regexps)
         {
             return new Regex($"{Group(regexps).ToString()}+");
         }
 
-        /**
-         * anchored anchors the regular expression by adding start and end delimiters.
-         */
+        /// <summary>
+        /// anchored anchors the regular expression by adding start and end delimiters.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> The anchored <see cref="Regex"/>. </returns>
         public static Regex Anchored(params Regex[] regexps)
         {
             return new Regex($"^{Expression(regexps).ToString()}$");
         }
 
-        /**
-         * capture wraps the expression in a capturing group.
-         */
+        /// <summary>
+        /// capture wraps the expression in a capturing group.
+        /// </summary>
+        /// <param name="regexps">list of Regular expressions.</param>
+        /// <returns> The captured <see cref="Regex"/>. </returns>
         public static Regex Capture(params Regex[] regexps)
         {
             return new Regex($"({Expression(regexps).ToString()})");

src/Microsoft.ComponentDetection.Common/FastDirectoryWalkerFactory.cs

@@ -200,7 +200,7 @@ public IObservable<FileSystemInfo> GetDirectoryScanner(DirectoryInfo root, Concu
         /// Initialized an observable file enumerator.
         /// </summary>
         /// <param name="root">Root directory to scan.</param>
-        /// <param name="directoryExclusionPredicate"></param>
+        /// <param name="directoryExclusionPredicate">predicate for excluding directories.</param>
         /// <param name="minimumConnectionCount">Number of observers that need to subscribe before the observable connects and starts enumerating.</param>
         /// <param name="filePatterns">Pattern used to filter files.</param>
         public void Initialize(DirectoryInfo root, ExcludeDirectoryPredicate directoryExclusionPredicate, int minimumConnectionCount, IEnumerable<string> filePatterns = null)

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.
         /// </summary>
-        /// <param name="path"></param>
-        /// <param name="output"></param>
-        /// <returns></returns>
+        /// <param name="path"> The path to resolve. </param>
+        /// <param name="output"> The pointer output. </param>
+        /// <returns> A pointer <see cref= "IntPtr"/> to the absolute path of a file. </returns>
         [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.
         /// </summary>
-        /// <param name="toFree"></param>
+        /// <param name="toFree">Pointer to the memory space to free. </param>
         [DllImport("libc", EntryPoint = "free")]
         public static extern void FreeMemoryLinux([In] IntPtr toFree);
 

src/Microsoft.ComponentDetection.Common/Telemetry/TelemetryRelay.cs

@@ -42,7 +42,7 @@ public static TelemetryRelay Instance
         /// <summary>
         /// Post a given telemetry record to all telemetry services.
         /// </summary>
-        /// <param name="record"></param>
+        /// <param name="record">Record to post. </param>
         public void PostTelemetryRecord(IDetectionTelemetryRecord record)
         {
             foreach (var service in TelemetryServices)

src/Microsoft.ComponentDetection.Contracts/FileComponentDetector.cs

@@ -70,7 +70,7 @@ private Task<IndividualDetectorScanResult> ScanDirectoryAsync(ScanRequest reques
         /// </summary>
         /// <param name="sourceDirectory">The directory to search.</param>
         /// <param name="exclusionPredicate">The exclusion predicate function.</param>
-        /// <returns></returns>
+        /// <returns>Awaitable task with enumerable streams <see cref="IEnumerable{IComponentStream}"/> for the declared detector. </returns>
         protected Task<IEnumerable<IComponentStream>> GetFileStreamsAsync(DirectoryInfo sourceDirectory, ExcludeDirectoryPredicate exclusionPredicate)
         {
             return Task.FromResult(this.ComponentStreamEnumerableFactory.GetComponentStreams(sourceDirectory, this.SearchPatterns, exclusionPredicate));

src/Microsoft.ComponentDetection.Contracts/IComponentDetector.cs

@@ -33,7 +33,7 @@ public interface IComponentDetector
         /// <summary>
         ///  Run the detector and return the result set of components found.
         /// </summary>
-        /// <returns></returns>
+        /// <returns> Awaitable task with result of components found. </returns>
         Task<IndividualDetectorScanResult> ExecuteDetectorAsync(ScanRequest request);
 
         /// <summary>

src/Microsoft.ComponentDetection.Contracts/IComponentRecorder.cs

@@ -27,7 +27,6 @@ public interface ISingleFileComponentRecorder
         /// <param name="parentComponentId">Id of the parent component.</param>
         /// <param name="isDevelopmentDependency">Boolean value indicating whether or not a component is a development-time dependency. Null implies that the value is unknown.</param>
         /// <param name="dependencyScope">Enum value indicating scope of the component. </param>
-        /// <returns>DetectedComponent added or updated.</returns>
         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.
         /// </summary>
         /// <param name="componentId">The componentId to check.</param>
+        /// <returns> DependencyScope <see cref="DependencyScope"/> for the given componentId. </returns>
         DependencyScope? GetDependencyScope(string componentId);
 
         /// <summary>

src/Microsoft.ComponentDetection.Contracts/IComponentStreamEnumerableFactory.cs

@@ -14,7 +14,7 @@ public interface IComponentStreamEnumerableFactory
         /// <param name="searchPatterns">The patterns to use in the search.</param>
         /// <param name="directoryExclusionPredicate">Predicate which indicates which directories should be excluded.</param>
         /// <param name="recursivelyScanDirectories">Indicates whether the streams should enumerate files from sub directories.</param>
-        /// <returns></returns>
+        /// <returns> Enumerable of <see cref="IComponentStream"/> files that matched the given search pattern and directory exclusion predicate.</returns>
         IEnumerable<IComponentStream> GetComponentStreams(DirectoryInfo directory, IEnumerable<string> searchPatterns, ExcludeDirectoryPredicate directoryExclusionPredicate, bool recursivelyScanDirectories = true);
 
         /// <summary>
@@ -25,7 +25,7 @@ public interface IComponentStreamEnumerableFactory
         /// <param name="fileMatchingPredicate">Predicate which indicates what files should be included.</param>
         /// <param name="directoryExclusionPredicate">Predicate which indicates which directories should be excluded.</param>
         /// <param name="recursivelyScanDirectories">Indicates whether the streams should enumerate files from sub directories.</param>
-        /// <returns></returns>
+        /// <returns> Enumerable of <see cref="IComponentStream"/> files that matched the given file matching predicate and directory exclusion predicate. </returns>
         IEnumerable<IComponentStream> GetComponentStreams(DirectoryInfo directory, Func<FileInfo, bool> fileMatchingPredicate, ExcludeDirectoryPredicate directoryExclusionPredicate, bool recursivelyScanDirectories = true);
     }
 }

src/Microsoft.ComponentDetection.Contracts/IPathUtilityService.cs

@@ -1,4 +1,4 @@
-namespace Microsoft.ComponentDetection.Contracts
+namespace Microsoft.ComponentDetection.Contracts
 {
     /// <summary>
     /// Wraps some common folder operations, shared across command line app and service.
@@ -10,24 +10,24 @@ public interface IPathUtilityService
         /// <summary>
         /// Given a path, resolve the underlying path, traversing any symlinks (man 2 lstat :D ).
         /// </summary>
-        /// <param name="path"></param>
-        /// <returns></returns>
+        /// <param name="path">Path that needs to be resolved. </param>
+        /// <returns> Returns a string of the underlying path. </returns>
         string ResolvePhysicalPath(string path);
 
         /// <summary>
         /// Returns true when the below file path exists under the above file path.
         /// </summary>
-        /// <param name="aboveFilePath"></param>
-        /// <param name="belowFilePath"></param>
-        /// <returns></returns>
+        /// <param name="aboveFilePath">The top file path. </param>
+        /// <param name="belowFilePath">The file path to find within the top file path. </param>
+        /// <returns> Return a bool. True, if below file path is found under above file path, otherwise false. </returns>
         bool IsFileBelowAnother(string aboveFilePath, string belowFilePath);
 
         /// <summary>
         /// Returns true if file name matches pattern.
         /// </summary>
         /// <param name="searchPattern">Search pattern.</param>
         /// <param name="fileName">File name without directory.</param>
-        /// <returns></returns>
+        /// <returns>Returns true if file name matches a pattern, otherwise false. </returns>
         bool MatchesPattern(string searchPattern, string fileName);
     }
 }

src/Microsoft.ComponentDetection.Detectors/linux/LinuxContainerDetector.cs

@@ -83,7 +83,7 @@ public async Task<IndividualDetectorScanResult> ExecuteDetectorAsync(ScanRequest
         /// Extracts and returns the timeout defined by the user, or a default value if one is not provided.
         /// </summary>
         /// <param name="detectorArgs">The arguments provided by the user.</param>
-        /// <returns></returns>
+        /// <returns> Time interval <see cref="TimeSpan"/> repesenting the timeout defined by the user, or a default value if one is not provided. </returns>
         private static TimeSpan GetTimeout(IDictionary<string, string> detectorArgs)
         {
             if (detectorArgs == null || !detectorArgs.TryGetValue("Linux.ScanningTimeoutSec", out var timeout))

src/Microsoft.ComponentDetection.Detectors/nuget/NuGetComponentDetector.cs

@@ -222,8 +222,8 @@ private IList<DirectoryInfo> GetRepositoryPathsFromNugetConfig(IComponentStream
         /// <summary>
         /// Checks to make sure a path is valid (does not have to exist).
         /// </summary>
-        /// <param name="potentialPath"></param>
-        /// <returns></returns>
+        /// <param name="potentialPath"> The path to validate. </param>
+        /// <returns>True if path is valid, otherwise it retuns false. </returns>
         private bool IsValidPath(string potentialPath)
         {
             FileInfo fileInfo = null;

src/Microsoft.ComponentDetection.Detectors/pip/PipDependencySpecification.cs

@@ -55,7 +55,7 @@ public class PipDependencySpecification
         /// <summary>
         /// Whether or not the package is safe to resolve based on the packagesToIgnore.
         /// </summary>
-        /// <returns></returns>
+        /// <returns> True if the package is unsafe, otherwise false. </returns>
         public bool PackageIsUnsafe()
         {
             return PackagesToIgnore.Contains(this.Name);

src/Microsoft.ComponentDetection.Detectors/pip/PythonVersionUtilities.cs

@@ -11,7 +11,7 @@ public static class PythonVersionUtilities
         /// </summary>
         /// <param name="version">Version.</param>
         /// <param name="specs">Version specifications.</param>
-        /// <returns></returns>
+        /// <returns>True if the version is valid for all specs, otherwise false. </returns>
         /// <exception cref="ArgumentException">The version or any of the specs are an invalid python version.</exception>
         public static bool VersionValidForSpec(string version, IList<string> specs)
         {

src/Microsoft.ComponentDetection.Detectors/rust/RustCrateUtilities.cs

@@ -225,7 +225,7 @@ public static CargoDependencyData ExtractRootDependencyAndWorkspaceSpecification
         /// <param name="rootLockFileInfo">The FileInfo for the cargo.lock file found in the root directory.</param>
         /// <param name="definedWorkspaces">A list of relative folder paths to include in search.</param>
         /// <param name="definedExclusions">A list of relative folder paths to exclude from search.</param>
-        /// <returns></returns>
+        /// <returns> Returns predicate <see cref="ExcludeDirectoryPredicate"/> which will be used to exclude directories. </returns>
         public static ExcludeDirectoryPredicate BuildExcludeDirectoryPredicateFromWorkspaces(FileInfo rootLockFileInfo, HashSet<string> definedWorkspaces, HashSet<string> definedExclusions)
         {
             var workspaceGlobs = BuildGlobMatchingFromWorkspaces(rootLockFileInfo, definedWorkspaces);
@@ -314,7 +314,7 @@ private static void GenerateDependencies(TomlTable cargoToml, IList<DependencySp
         /// </summary>
         /// <param name="rootLockFileInfo">The FileInfo for the cargo.lock file found in the root directory.</param>
         /// <param name="definedWorkspaces">A list of relative folder paths to include in search.</param>
-        /// <returns></returns>
+        /// <returns>Dictionary with worspace paths and their corresponding Globs.</returns>
         private static Dictionary<string, Glob> BuildGlobMatchingFromWorkspaces(FileInfo rootLockFileInfo, HashSet<string> definedWorkspaces)
         {
             var directoryGlobs = new Dictionary<string, Glob>

src/Microsoft.ComponentDetection.Detectors/yarn/Parsers/YarnBlockFile.cs

@@ -150,8 +150,8 @@ private void ReadVersionHeader()
         /// <summary>
         /// Parses a block and its sub-blocks into <see cref="YarnBlock"/>.
         /// </summary>
-        /// <param name="level"></param>
-        /// <returns></returns>
+        /// <param name="level"> Level to get block from in YarnBlock file. </param>
+        /// <returns>Yarnblock <see cref="YarnBlock"/> gotten from the parsed block. </returns>
         private YarnBlock ParseBlock(int level = 0)
         {
             var currentLevelDelimiter = "  ";
@@ -204,7 +204,7 @@ private YarnBlock ParseBlock(int level = 0)
         /// <summary>
         /// Increments the internal pointer so that it is at the next block.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>True if the pointer was succesfully incremented.</returns>
         private bool ReadToNextMajorBlock()
         {
             string line;
@@ -234,7 +234,7 @@ private bool IncrementIndex()
         /// <summary>
         /// Checks to see if any lines are left in the file contents.
         /// </summary>
-        /// <returns></returns>
+        /// <returns>True if there are any lines left in the file.</returns>
         private bool Peek()
         {
             if (this.fileLineIndex >= this.fileLines.Count)

src/Microsoft.ComponentDetection.Detectors/yarn/YarnLockComponentDetector.cs

@@ -170,7 +170,7 @@ private void ParseTreeWithAssignedRoot(YarnEntry root, Dictionary<string, YarnEn
         /// <param name="location">The file location of the yarn.lock file.</param>
         /// <param name="yarnEntries">All the yarn entries that we know about.</param>
         /// <param name="yarnRoots">The output yarnRoots that we care about using as starting points.</param>
-        /// <returns></returns>
+        /// <returns>False if no package.json file was found at location, otherwise it returns true. </returns>
         private bool TryReadPeerPackageJsonRequestsAsYarnEntries(string location, Dictionary<string, YarnEntry> yarnEntries, out List<YarnEntry> yarnRoots)
         {
             yarnRoots = new List<YarnEntry>();