diff --git a/.editorconfig b/.editorconfig index 2953ae8d9..48f4d1c5a 100644 --- a/.editorconfig +++ b/.editorconfig @@ -36,6 +36,12 @@ dotnet_diagnostic.CS0414.severity = error dotnet_diagnostic.CS0618.severity = suggestion # CS0649: Uninitialized private or internal field declaration that is never assigned a value dotnet_diagnostic.CS0649.severity = error +# CS1570: Parameter has no matching param tag in the XML comment +dotnet_diagnostic.CS1570.severity = silent +# CS1574: XML comment has cref attribute that could not be resolved. +dotnet_diagnostic.CS1574.severity = suggestion +# CS1591: Missing XML comment for publicly visible type or member +dotnet_diagnostic.CS1591.severity = silent # CS1998: This async method lacks 'await' operators and will run synchronously dotnet_diagnostic.CS1998.severity = suggestion # CS4014: Consider applying the await operator to the result of the call diff --git a/PowerShellEditorServices.Common.props b/PowerShellEditorServices.Common.props index 925819027..56fc80417 100644 --- a/PowerShellEditorServices.Common.props +++ b/PowerShellEditorServices.Common.props @@ -14,6 +14,8 @@ true true + + true true diff --git a/src/PowerShellEditorServices.Hosting/Configuration/HostLogger.cs b/src/PowerShellEditorServices.Hosting/Configuration/HostLogger.cs index 73de784a9..79ac55516 100644 --- a/src/PowerShellEditorServices.Hosting/Configuration/HostLogger.cs +++ b/src/PowerShellEditorServices.Hosting/Configuration/HostLogger.cs @@ -15,9 +15,9 @@ namespace Microsoft.PowerShell.EditorServices.Hosting /// User-facing log level for editor services configuration. /// /// - /// The underlying values of this enum attempt to align to both and . + /// The underlying values of this enum attempt to align to both + /// and + /// . /// public enum PsesLogLevel { diff --git a/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs b/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs index f082975a1..06bc9acf4 100644 --- a/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs +++ b/src/PowerShellEditorServices.Hosting/EditorServicesLoader.cs @@ -2,7 +2,6 @@ // Licensed under the MIT License. using System; -using System.Diagnostics; using System.IO; using System.Reflection; using System.Threading.Tasks; @@ -13,6 +12,10 @@ using System.Management.Automation; using System.Management.Automation.Runspaces; +#if DEBUG +using System.Diagnostics; +#endif + #if CoreCLR using System.Runtime.Loader; #else @@ -58,6 +61,7 @@ public static EditorServicesLoader Create( /// The host logger to use. /// The host configuration to start editor services with. /// The session file writer to write the session file with. + /// The loggers to unsubscribe form writing to the terminal. /// public static EditorServicesLoader Create( HostLogger logger, diff --git a/src/PowerShellEditorServices/Extensions/Api/EditorExtensionServiceProvider.cs b/src/PowerShellEditorServices/Extensions/Api/EditorExtensionServiceProvider.cs index cd5cc2924..dc2809962 100644 --- a/src/PowerShellEditorServices/Extensions/Api/EditorExtensionServiceProvider.cs +++ b/src/PowerShellEditorServices/Extensions/Api/EditorExtensionServiceProvider.cs @@ -54,11 +54,6 @@ internal EditorExtensionServiceProvider(IServiceProvider serviceProvider) /// public ILanguageServerService LanguageServer { get; } - /// - /// Service providing document symbol provider registration. - /// - // public IDocumentSymbolService DocumentSymbols { get; } - /// /// Service providing extension command registration and functionality. /// @@ -93,7 +88,7 @@ internal EditorExtensionServiceProvider(IServiceProvider serviceProvider) /// /// Get an underlying service object from PSES by type name. /// - /// The full type name of the service to get. + /// The full type name of the service to get. /// The assembly name from which the service comes. /// The service object requested, or null if no service of that type name exists. /// diff --git a/src/PowerShellEditorServices/Extensions/EditorObject.cs b/src/PowerShellEditorServices/Extensions/EditorObject.cs index f1bcd0b8b..cfbd97254 100644 --- a/src/PowerShellEditorServices/Extensions/EditorObject.cs +++ b/src/PowerShellEditorServices/Extensions/EditorObject.cs @@ -73,6 +73,7 @@ public class EditorObject /// /// Creates a new instance of the EditorObject class. /// + /// The service provider? /// An ExtensionService which handles command registration. /// An IEditorOperations implementation which handles operations in the host editor. internal EditorObject( diff --git a/src/PowerShellEditorServices/Extensions/FileContext.cs b/src/PowerShellEditorServices/Extensions/FileContext.cs index 0841f0cc3..ddd84029d 100644 --- a/src/PowerShellEditorServices/Extensions/FileContext.cs +++ b/src/PowerShellEditorServices/Extensions/FileContext.cs @@ -122,7 +122,7 @@ public string GetText(FileRange bufferRange) /// /// Gets the file content in the specified range as an array of strings. /// - /// The buffer range for which content will be extracted. + /// The buffer range for which content will be extracted. /// An array of strings, each representing a line in the file within the specified range. public string[] GetTextLines(FileRange fileRange) => scriptFile.GetLinesInRange(fileRange.ToBufferRange()); diff --git a/src/PowerShellEditorServices/Hosting/EditorServicesServerFactory.cs b/src/PowerShellEditorServices/Hosting/EditorServicesServerFactory.cs index 72109788c..361d292ea 100644 --- a/src/PowerShellEditorServices/Hosting/EditorServicesServerFactory.cs +++ b/src/PowerShellEditorServices/Hosting/EditorServicesServerFactory.cs @@ -2,7 +2,6 @@ // Licensed under the MIT License. using System; -using System.Diagnostics; using System.IO; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Logging; @@ -14,6 +13,7 @@ using Microsoft.PowerShell.EditorServices.Services.Extension; #if DEBUG +using System.Diagnostics; using Serilog.Debugging; #endif @@ -36,7 +36,7 @@ internal sealed class EditorServicesServerFactory : IDisposable /// /// /// This can only be called once because it sets global state (the logger) and that call is - /// in . + /// in . /// /// /// TODO: Why is this a static function wrapping a constructor instead of just a @@ -45,7 +45,7 @@ internal sealed class EditorServicesServerFactory : IDisposable /// /// The path of the log file to use. /// The minimum log level to use. - /// + /// The host logger? public static EditorServicesServerFactory Create(string logPath, int minimumLogLevel, IObservable<(int logLevel, string message)> hostLogger) { Log.Logger = new LoggerConfiguration() @@ -78,7 +78,7 @@ public static EditorServicesServerFactory Create(string logPath, int minimumLogL /// Create the LSP server. /// /// - /// This is only called once and that's in . + /// This is only called once and that's in . /// /// The protocol transport input stream. /// The protocol transport output stream. @@ -94,7 +94,7 @@ public PsesLanguageServer CreateLanguageServer( /// Create the debug server given a language server instance. /// /// - /// This is only called once and that's in . + /// This is only called once and that's in . /// /// The protocol transport input stream. /// The protocol transport output stream. @@ -116,7 +116,7 @@ public PsesDebugServer CreateDebugServerWithLanguageServer( /// Create a new debug server based on an old one in an ended session. /// /// - /// This is only called once and that's in . + /// This is only called once and that's in . /// /// The protocol transport input stream. /// The protocol transport output stream. diff --git a/src/PowerShellEditorServices/Hosting/HostStartupInfo.cs b/src/PowerShellEditorServices/Hosting/HostStartupInfo.cs index ccf5c7c9a..e34df5912 100644 --- a/src/PowerShellEditorServices/Hosting/HostStartupInfo.cs +++ b/src/PowerShellEditorServices/Hosting/HostStartupInfo.cs @@ -101,7 +101,7 @@ public sealed class HostStartupInfo /// The minimum log level of log events to be logged. /// /// - /// This is cast to all of , , , and , hence it is an int. /// @@ -131,8 +131,7 @@ public sealed class HostStartupInfo /// /// The host application's version. /// The PowerShell host to use. - /// The path to the shared profile. - /// The path to the user specific profile. + /// The set of profile paths. /// Flags of features to enable. /// Names or paths of additional modules to import. /// The language mode inherited from the orginal PowerShell process. This will be used when creating runspaces so that we honor the same initialSessionState including allowed modules, cmdlets and language mode. diff --git a/src/PowerShellEditorServices/Services/Analysis/AnalysisService.cs b/src/PowerShellEditorServices/Services/Analysis/AnalysisService.cs index 9f511c37a..072115bbc 100644 --- a/src/PowerShellEditorServices/Services/Analysis/AnalysisService.cs +++ b/src/PowerShellEditorServices/Services/Analysis/AnalysisService.cs @@ -131,10 +131,8 @@ public AnalysisService( /// Sets up a script analysis run, eventually returning the result. /// /// The files to run script analysis on. - /// A cancellation token to cancel this call with. /// A task that finishes when script diagnostics have been published. - public void StartScriptDiagnostics( - ScriptFile[] filesToAnalyze) + public void StartScriptDiagnostics(ScriptFile[] filesToAnalyze) { if (!_configurationService.CurrentSettings.ScriptAnalysis.Enable) { @@ -219,7 +217,7 @@ public async Task GetCommentHelpText(string functionText, string helpLoc /// /// Get the most recent corrections computed for a given script file. /// - /// The URI string of the file to get code actions for. + /// The URI string of the file to get code actions for. /// A threadsafe readonly dictionary of the code actions of the particular file. public async Task>> GetMostRecentCodeActionsForFileAsync(DocumentUri uri) { @@ -245,7 +243,7 @@ public async Task>> Ge /// /// Event subscription method to be run when PSES configuration has been updated. /// - /// The sender of the configuration update event. + /// The sender of the configuration update event. /// The new language server settings. public void OnConfigurationUpdated(object _, LanguageServerSettings settings) { diff --git a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointApiUtils.cs b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointApiUtils.cs index c7ea90e45..d5ce11927 100644 --- a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointApiUtils.cs +++ b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointApiUtils.cs @@ -167,6 +167,7 @@ public static Breakpoint SetBreakpoint(Debugger debugger, BreakpointDetailsBase /// The expression that needs to be true for the breakpoint to be triggered. /// The amount of times this line should be hit til the breakpoint is triggered. /// The log message to write instead of calling 'break'. In VS Code, this is called a 'logPoint'. + /// The error message we might return. /// ScriptBlock public static ScriptBlock GetBreakpointActionScriptBlock(string condition, string hitCondition, string logMessage, out string errorMessage) { diff --git a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointDetails.cs b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointDetails.cs index 4317b0ad3..0a1c268b9 100644 --- a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointDetails.cs +++ b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/BreakpointDetails.cs @@ -49,6 +49,7 @@ private BreakpointDetails() /// /// /// + /// /// internal static BreakpointDetails Create( string source, diff --git a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/DebuggerStoppedEventArgs.cs b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/DebuggerStoppedEventArgs.cs index 0b2d47c30..dd94d9290 100644 --- a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/DebuggerStoppedEventArgs.cs +++ b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/DebuggerStoppedEventArgs.cs @@ -59,7 +59,7 @@ internal class DebuggerStoppedEventArgs /// Creates a new instance of the DebuggerStoppedEventArgs class. /// /// The original DebuggerStopEventArgs instance from which this instance is based. - /// The RunspaceDetails of the runspace which raised this event. + /// The RunspaceDetails of the runspace which raised this event. public DebuggerStoppedEventArgs( DebuggerStopEventArgs originalEvent, IRunspaceInfo runspaceInfo) @@ -71,7 +71,7 @@ public DebuggerStoppedEventArgs( /// Creates a new instance of the DebuggerStoppedEventArgs class. /// /// The original DebuggerStopEventArgs instance from which this instance is based. - /// The RunspaceDetails of the runspace which raised this event. + /// The RunspaceDetails of the runspace which raised this event. /// The local path of the remote script being debugged. public DebuggerStoppedEventArgs( DebuggerStopEventArgs originalEvent, diff --git a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/StackFrameDetails.cs b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/StackFrameDetails.cs index b749d67d4..6a8704df8 100644 --- a/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/StackFrameDetails.cs +++ b/src/PowerShellEditorServices/Services/DebugAdapter/Debugging/StackFrameDetails.cs @@ -83,6 +83,9 @@ internal class StackFrameDetails /// /// A variable container with all the filtered, auto variables for this stack frame. /// + /// + /// A variable container with all the command variables for this stack frame. + /// /// A new instance of the StackFrameDetails class. internal static StackFrameDetails Create( PSObject callStackFrameObject, diff --git a/src/PowerShellEditorServices/Services/Extension/ExtensionService.cs b/src/PowerShellEditorServices/Services/Extension/ExtensionService.cs index 30acf01bd..eb8bd2859 100644 --- a/src/PowerShellEditorServices/Services/Extension/ExtensionService.cs +++ b/src/PowerShellEditorServices/Services/Extension/ExtensionService.cs @@ -117,6 +117,7 @@ internal Task InitializeAsync() /// /// The unique name of the command to be invoked. /// The context in which the command is being invoked. + /// The token used to cancel this. /// A Task that can be awaited for completion. /// The command being invoked was not registered. public Task InvokeCommandAsync(string commandName, EditorContext editorContext, CancellationToken cancellationToken) diff --git a/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellContextFrame.cs b/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellContextFrame.cs index 2db852c6e..d837fb5d2 100644 --- a/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellContextFrame.cs +++ b/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellContextFrame.cs @@ -3,12 +3,15 @@ using System; using System.Diagnostics; -using System.Text; using Microsoft.Extensions.Logging; using Microsoft.PowerShell.EditorServices.Services.PowerShell.Runspace; using Microsoft.PowerShell.EditorServices.Services.PowerShell.Utility; using SMA = System.Management.Automation; +#if DEBUG +using System.Text; +#endif + namespace Microsoft.PowerShell.EditorServices.Services.PowerShell.Context { [DebuggerDisplay("{ToDebuggerDisplayString()}")] diff --git a/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellVersionDetails.cs b/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellVersionDetails.cs index 14e924c3a..957a032f8 100644 --- a/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellVersionDetails.cs +++ b/src/PowerShellEditorServices/Services/PowerShell/Context/PowerShellVersionDetails.cs @@ -91,6 +91,7 @@ public PowerShellVersionDetails( /// Gets the PowerShell version details for the given runspace. /// /// An ILogger implementation used for writing log messages. + /// The PowerShell instance for which to to get the version. /// A new PowerShellVersionDetails instance. public static PowerShellVersionDetails GetVersionDetails(ILogger logger, PowerShell pwsh) { diff --git a/src/PowerShellEditorServices/Services/PowerShell/Runspace/SessionDetails.cs b/src/PowerShellEditorServices/Services/PowerShell/Runspace/SessionDetails.cs index 2683e1992..4eeaf165c 100644 --- a/src/PowerShellEditorServices/Services/PowerShell/Runspace/SessionDetails.cs +++ b/src/PowerShellEditorServices/Services/PowerShell/Runspace/SessionDetails.cs @@ -43,7 +43,6 @@ public static SessionDetails GetFromPowerShell(PowerShell pwsh) /// contained in the PSObject which was obtained using the /// PSCommand returned by GetDetailsCommand. /// - /// public SessionDetails( int processId, string computerName, diff --git a/src/PowerShellEditorServices/Services/PowerShell/Utility/CommandHelpers.cs b/src/PowerShellEditorServices/Services/PowerShell/Utility/CommandHelpers.cs index c5963ef78..67547a0e1 100644 --- a/src/PowerShellEditorServices/Services/PowerShell/Utility/CommandHelpers.cs +++ b/src/PowerShellEditorServices/Services/PowerShell/Utility/CommandHelpers.cs @@ -59,6 +59,7 @@ internal static class CommandHelpers /// The name of the command. /// The current runspace. /// The execution service. + /// The token used to cancel this. /// A CommandInfo object with details about the specified command. public static async Task GetCommandInfoAsync( string commandName, @@ -117,6 +118,7 @@ public static async Task GetCommandInfoAsync( /// /// The CommandInfo instance for the command. /// The execution service to use for getting command documentation. + /// The token used to cancel this. /// The synopsis. public static async Task GetCommandSynopsisAsync( CommandInfo commandInfo, diff --git a/src/PowerShellEditorServices/Services/Symbols/ScriptDocumentSymbolProvider.cs b/src/PowerShellEditorServices/Services/Symbols/ScriptDocumentSymbolProvider.cs index 9c17f17d5..92b33c8de 100644 --- a/src/PowerShellEditorServices/Services/Symbols/ScriptDocumentSymbolProvider.cs +++ b/src/PowerShellEditorServices/Services/Symbols/ScriptDocumentSymbolProvider.cs @@ -30,7 +30,6 @@ IEnumerable IDocumentSymbolProvider.ProvideDocumentSymbols( /// Finds all symbols in a script /// /// The abstract syntax tree of the given script - /// The PowerShell version the Ast was generated from /// A collection of SymbolReference objects public static IEnumerable FindSymbolsInDocument(Ast scriptAst) { diff --git a/src/PowerShellEditorServices/Services/Symbols/Vistors/AstOperations.cs b/src/PowerShellEditorServices/Services/Symbols/Vistors/AstOperations.cs index 1bdcb0ec0..ee364107c 100644 --- a/src/PowerShellEditorServices/Services/Symbols/Vistors/AstOperations.cs +++ b/src/PowerShellEditorServices/Services/Symbols/Vistors/AstOperations.cs @@ -55,7 +55,7 @@ static AstOperations() /// /// The 1-based file offset at which a symbol will be located. /// - /// + /// /// The PowerShellContext to use for gathering completions. /// /// An ILogger implementation used for writing log messages. @@ -195,7 +195,6 @@ public static SymbolReference FindDefinitionOfSymbol( /// Finds all symbols in a script /// /// The abstract syntax tree of the given script - /// The PowerShell version the Ast was generated from /// A collection of SymbolReference objects public static IEnumerable FindSymbolsInDocument(Ast scriptAst) { diff --git a/src/PowerShellEditorServices/Services/Template/TemplateService.cs b/src/PowerShellEditorServices/Services/Template/TemplateService.cs index ae9cc3c9b..1427ba174 100644 --- a/src/PowerShellEditorServices/Services/Template/TemplateService.cs +++ b/src/PowerShellEditorServices/Services/Template/TemplateService.cs @@ -34,7 +34,7 @@ internal class TemplateService /// /// Creates a new instance of the TemplateService class. /// - /// The PowerShellContext to use for this service. + /// The PowerShellContext to use for this service. /// An ILoggerFactory implementation used for writing log messages. public TemplateService(IInternalPowerShellExecutionService executionService, ILoggerFactory factory) { diff --git a/src/PowerShellEditorServices/Services/TextDocument/Handlers/CompletionHandler.cs b/src/PowerShellEditorServices/Services/TextDocument/Handlers/CompletionHandler.cs index 288d14774..4bf174cac 100644 --- a/src/PowerShellEditorServices/Services/TextDocument/Handlers/CompletionHandler.cs +++ b/src/PowerShellEditorServices/Services/TextDocument/Handlers/CompletionHandler.cs @@ -109,6 +109,7 @@ public override async Task Handle(CompletionItem request, Cancel /// /// The 1-based column number at which completions will be gathered. /// + /// The token used to cancel this. /// /// A CommandCompletion instance completions for the identified statement. /// diff --git a/src/PowerShellEditorServices/Services/Workspace/LanguageServerSettings.cs b/src/PowerShellEditorServices/Services/Workspace/LanguageServerSettings.cs index 2a87ed97c..9f59d87dc 100644 --- a/src/PowerShellEditorServices/Services/Workspace/LanguageServerSettings.cs +++ b/src/PowerShellEditorServices/Services/Workspace/LanguageServerSettings.cs @@ -209,6 +209,7 @@ public CodeFormattingSettings(CodeFormattingSettings codeFormattingSettings) /// /// The tab size in the number spaces. /// If true, insert spaces otherwise insert tabs for indentation. + /// The logger instance. public Hashtable GetPSSASettingsHashtable( int tabSize, bool insertSpaces, diff --git a/src/PowerShellEditorServices/Services/Workspace/RemoteFileManagerService.cs b/src/PowerShellEditorServices/Services/Workspace/RemoteFileManagerService.cs index f986c8eba..6c0b9bd1c 100644 --- a/src/PowerShellEditorServices/Services/Workspace/RemoteFileManagerService.cs +++ b/src/PowerShellEditorServices/Services/Workspace/RemoteFileManagerService.cs @@ -245,7 +245,8 @@ function New-EditorFile { /// Creates a new instance of the RemoteFileManagerService class. /// /// An ILoggerFactory implementation used for writing log messages. - /// + /// The runspace we're using. + /// /// The PowerShellContext to use for file loading operations. /// /// diff --git a/src/PowerShellEditorServices/Services/Workspace/WorkspaceService.cs b/src/PowerShellEditorServices/Services/Workspace/WorkspaceService.cs index 6f8e43e49..d82b3b734 100644 --- a/src/PowerShellEditorServices/Services/Workspace/WorkspaceService.cs +++ b/src/PowerShellEditorServices/Services/Workspace/WorkspaceService.cs @@ -80,8 +80,6 @@ internal class WorkspaceService /// /// Creates a new instance of the Workspace class. /// - /// The version of PowerShell for which scripts will be parsed. - /// An ILogger implementation used for writing log messages. public WorkspaceService(ILoggerFactory factory) { powerShellVersion = VersionUtils.PSVersion; @@ -108,18 +106,6 @@ public WorkspaceService(ILoggerFactory factory) /// public ScriptFile GetFile(string filePath) => GetFile(new Uri(filePath)); - /// - /// Gets an open file in the workspace. If the file isn't open but exists on the filesystem, load and return it. - /// IMPORTANT: Not all documents have a backing file e.g. untitled: scheme documents. Consider using - /// instead. - /// - /// The file URI at which the script resides. - /// - /// is not found. - /// - /// - /// contains a null or empty string. - /// public ScriptFile GetFile(Uri fileUri) => GetFile(DocumentUri.From(fileUri)); /// @@ -128,12 +114,8 @@ public WorkspaceService(ILoggerFactory factory) /// instead. /// /// The document URI at which the script resides. - /// - /// is not found. - /// - /// - /// contains a null or empty string. - /// + /// + /// public ScriptFile GetFile(DocumentUri documentUri) { Validate.IsNotNull(nameof(documentUri), documentUri); @@ -349,7 +331,7 @@ public string GetRelativePath(string filePath) resolvedPath = workspaceUri.MakeRelativeUri(fileUri).ToString(); // Convert the directory separators if necessary - if (System.IO.Path.DirectorySeparatorChar == '\\') + if (Path.DirectorySeparatorChar == '\\') { resolvedPath = resolvedPath.Replace('/', '\\'); }