Document.

Author: sharpjs

PSql/Commands/ConnectSqlCommand.cs

@@ -1,31 +1,36 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// Don't require doc comments.  Commands are documented via a help file.
-#pragma warning disable CS1591
-
 namespace PSql.Commands;
 
 /// <summary>
 ///   The <c>Connect-Sql</c> command.
+///   Opens a connection to SQL Server, Azure SQL Database, or compatible
+///   database.
 /// </summary>
 [Cmdlet(VerbsCommunications.Connect, "Sql")]
 [OutputType(typeof(SqlConnection))]
 public class ConnectSqlCommand : PSqlCmdlet
 {
     /// <summary>
-    ///   <b>-Context:</b> TODO
+    ///   <b>-Context:</b>
+    ///   An object containing information necessary to connect to SQL Server,
+    ///   Azure SQL Database, or compatible database.  Obtain via
+    ///   <c>New-SqlContext</c>.
     /// </summary>
     [Parameter(Position = 0, ValueFromPipeline = true)]
     public SqlContext? Context { get; set; }
 
     /// <summary>
-    ///   <b>-DatabaseName:</b> TODO
+    ///   <b>-DatabaseName:</b>
+    ///   An optional database name.  If specified, this parameter overrides
+    ///   the database name, if any, specified in the <c>-Context</c>.
     /// </summary>
     [Parameter]
     [Alias("Database")]
     public string? DatabaseName { get; set; }
 
+    /// <inheritdoc/>
     protected override void ProcessRecord()
     {
         var context    = Context ?? new();

PSql/Commands/ConnectedCmdlet.cs

@@ -20,7 +20,7 @@ protected const string
     public SqlConnection? Connection { get; set; }
 
     /// <summary>
-    ///   <b>-Context:</b> TODO
+    ///   <b>-Context:</b>
     ///   An object containing information necessary to connect to SQL Server,
     ///   Azure SQL Database, or compatible database.  Obtain via
     ///   <c>New-SqlContext</c>.

PSql/Commands/DisconnectSqlCommand.cs

@@ -1,24 +1,24 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// Don't require doc comments.  Commands are documented via a help file.
-#pragma warning disable CS1591
-
 namespace PSql.Commands;
 
 /// <summary>
 ///   The <c>Disconnect-Sql</c> command.
+///   Closes a connection created by <c>Connect-Sql</c>.
 /// </summary>
 [Cmdlet(VerbsCommunications.Disconnect, "Sql")]
 [OutputType(typeof(void))]
 public class DisconnectSqlCommand : PSqlCmdlet
 {
     /// <summary>
-    ///   <b>-Connection:</b> TODO
+    ///   <b>-Connection:</b>
+    ///   An open database connection.  Obtain via <c>Connect-Sql</c>.
     /// </summary>
     [Parameter(Position = 0, ValueFromPipeline = true, ValueFromRemainingArguments = true)]
     public SqlConnection[]? Connection { get; set; }
 
+    /// <inheritdoc/>
     protected override void ProcessRecord()
     {
         if (Connection is { } connections)

PSql/Commands/ExpandSqlCmdDirectivesCommand.cs

@@ -7,27 +7,31 @@ namespace PSql.Commands;
 
 /// <summary>
 ///   The <c>Expand-SqlCmdDirectives</c> command.
+///   Performs limited SQLCMD-style preprocessing.
 /// </summary>
 [Cmdlet(VerbsData.Expand, "SqlCmdDirectives")]
 [OutputType(typeof(string[]))]
 public class ExpandSqlCmdDirectivesCommand : PSqlCmdlet
 {
     /// <summary>
-    ///   <b>-Sql:</b> TODO
+    ///   <b>-Sql:</b>
+    ///   SQL scripts(s) to process.
     /// </summary>
     [Parameter(Position = 0, Mandatory = true, ValueFromPipeline = true)]
     public string?[]? Sql { get; set; }
 
     /// <summary>
-    ///   <b>-Define:</b> TODO
+    ///   <b>-Define:</b>
+    ///   SQLCMD preprocessor variables to define.
     /// </summary>
     [Parameter(Position = 1)]
     public Hashtable? Define { get; set; }
 
     private readonly E.SqlCmdPreprocessor _preprocessor;
 
     /// <summary>
-    ///   Creates a new <see cref="ExpandSqlCmdDirectivesCommand"/> instance.
+    ///   Initializes a new <see cref="ExpandSqlCmdDirectivesCommand"/>
+    ///   instance.
     /// </summary>
     public ExpandSqlCmdDirectivesCommand()
     {

PSql/Commands/InvokeSqlCommand.cs

@@ -1,53 +1,58 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// Don't require doc comments.  Commands are documented via a help file.
-#pragma warning disable CS1591
-
 using System.Collections;
 
 namespace PSql.Commands;
 
 /// <summary>
 ///   The <c>Invoke-Sql</c> command.
+///   Runs SQL scripts on SQL Server, Azure SQL Database, or compatible
+///   systems.
 /// </summary>
 [Cmdlet(VerbsLifecycle.Invoke, "Sql", DefaultParameterSetName = ContextName)]
 [OutputType(typeof(PSObject[]))]
 public class InvokeSqlCommand : ConnectedCmdlet
 {
     /// <summary>
-    ///   <b>-Sql:</b> TODO
+    ///   <b>-Sql:</b>
+    ///   SQL scripts(s) to run.
     /// </summary>
     [Parameter(Position = 0, Mandatory = true, ValueFromPipeline = true)]
     public string?[]? Sql { get; set; }
 
     /// <summary>
-    ///   <b>-Define:</b> TODO
+    ///   <b>-Define:</b>
+    ///   SQLCMD preprocessor variables to define.
     /// </summary>
     [Parameter(Position = 1)]
     public Hashtable? Define { get; set; }
 
     /// <summary>
-    ///   <b>-NoPreprocessing:</b> TODO
+    ///   <b>-NoPreprocessing:</b>
+    ///   Disables SQLCMD preprocessing support.
     /// </summary>
     [Parameter]
     [Alias("NoSqlCmdMode")]
     public SwitchParameter NoPreprocessing { get; set; }
 
     /// <summary>
-    ///   <b>-NoErrorHandling:</b> TODO
+    ///   <b>-NoErrorHandling:</b>
+    ///   Disables the error-handling wrapper.
     /// </summary>
     [Parameter]
     public SwitchParameter NoErrorHandling { get; set; }
 
     /// <summary>
-    ///   <b>-UseSqlTypes:</b> TODO
+    ///   <b>-UseSqlTypes:</b>
+    ///   Reads column values using native SQL Server types instead of .NET types.
     /// </summary>
     [Parameter]
     public SwitchParameter UseSqlTypes { get; set; }
 
     /// <summary>
-    ///   <b>-Timeout:</b> TODO
+    ///   <b>-Timeout:</b>
+    ///   Maximum duration to wait for each SQL batch to complete.
     /// </summary>
     [Parameter]
     public TimeSpan? Timeout { get; set; }

PSql/Commands/NewSqlContextCommand.cs

@@ -1,9 +1,6 @@
 // Copyright Subatomix Research Inc.
 // SPDX-License-Identifier: MIT
 
-// Don't require doc comments.  Commands are documented via a help file.
-#pragma warning disable CS1591
-
 namespace PSql.Commands;
 
 using static ApplicationIntent;
@@ -12,6 +9,8 @@ namespace PSql.Commands;
 
 /// <summary>
 ///   The <c>New-SqlContext</c> command.
+///   Creates an object specifying how to connect to SQL Server, Azure SQL
+///   Database, or compatible system.
 /// </summary>
 [Cmdlet(VerbsCommon.New, nameof(SqlContext), DefaultParameterSetName = GenericName)]
 [OutputType(typeof(SqlContext))]
@@ -23,20 +22,24 @@ private const string
         CloneName   = "Clone";
 
     /// <summary>
-    ///   <b>-Azure:</b> TODO
+    ///   <b>-Azure:</b>
+    ///   Specifies that the context connects to Azure SQL Database.
     /// </summary>
     [Parameter(ParameterSetName = AzureName, Mandatory = true)]
     public SwitchParameter Azure { get; set; }
 
     /// <summary>
-    ///   <b>-Source:</b> TODO
+    ///   <b>-Source:</b>
+    ///   A context previously created by this cmdlet from which to copy
+    ///   property values into the created context.
     /// </summary>
     [Parameter(ParameterSetName = CloneName, Mandatory = true, ValueFromPipeline = true)]
     [ValidateNotNull]
     public SqlContext? Source { get; set; }
 
     /// <summary>
-    ///   <b>-ResourceGroupName:</b> TODO
+    ///   <b>-ResourceGroupName:</b>
+    ///   Name of the Azure resource group containing the database server.
     /// </summary>
     [Alias("ResourceGroup", "ServerResourceGroupName")]
     [Parameter(ParameterSetName = AzureName, Position = 0)]
@@ -45,7 +48,8 @@ private const string
     public string? ResourceGroupName { get; set; }
 
     /// <summary>
-    ///   <b>-ServerResourceName:</b> TODO
+    ///   <b>-ServerResourceName:</b>
+    ///   Azure resource name of the database server.
     /// </summary>
     [Alias("Resource")]
     [Parameter(ParameterSetName = AzureName,  Position = 1)]
@@ -54,7 +58,8 @@ private const string
     public string? ServerResourceName { get; set; }
 
     /// <summary>
-    ///   <b>-ServerName:</b> TODO
+    ///   <b>-ServerName:</b>
+    ///   DNS name of the database server.
     /// </summary>
     [Alias("Server")]
     [Parameter(ParameterSetName = GenericName, Position = 0)]
@@ -64,7 +69,8 @@ private const string
     public string? ServerName { get; set; }
 
     /// <summary>
-    ///   <b>-DatabaseName:</b> TODO
+    ///   <b>-DatabaseName:</b>
+    ///   Name of the database.
     /// </summary>
     [Alias("Database")]
     [Parameter(ParameterSetName = GenericName, Position = 1)]
@@ -74,31 +80,35 @@ private const string
     public string? DatabaseName { get; set; }
 
     /// <summary>
-    ///   <b>-AuthenticationMode:</b> TODO
+    ///   <b>-AuthenticationMode:</b>
+    ///   Method to use to authenticate with Azure SQL Database.
     /// </summary>
     [Alias("Auth")]
     [Parameter(ParameterSetName = AzureName)]
     [Parameter(ParameterSetName = CloneName)]
     public AzureAuthenticationMode AuthenticationMode { get; set; }
 
     /// <summary>
-    ///   <b>-Credential:</b> TODO
+    ///   <b>-Credential:</b>
+    ///   Credential to use to authenticate with the database server.
     /// </summary>
     [Parameter]
     [Credential]
     [AllowNull]
     public PSCredential? Credential { get; set; } = PSCredential.Empty;
 
     /// <summary>
-    ///   <b>-EncryptionMode:</b> TODO
+    ///   <b>-EncryptionMode:</b>
+    ///   Transport encryption to use for connections.
     /// </summary>
     [Alias("Encryption")]
     [Parameter(ParameterSetName = GenericName)]
     [Parameter(ParameterSetName = CloneName)]
     public EncryptionMode EncryptionMode { get; set; }
 
     /// <summary>
-    ///   <b>-ServerPort:</b> TODO
+    ///   <b>-ServerPort:</b>
+    ///   Remote TCP port of the database server.
     /// </summary>
     [Alias("Port")]
     [Parameter(ParameterSetName = GenericName)]
@@ -107,7 +117,8 @@ private const string
     public ushort? ServerPort { get; set; }
 
     /// <summary>
-    ///   <b>-InstanceName:</b> TODO
+    ///   <b>-InstanceName:</b>
+    ///   Name of the database engine instance.
     /// </summary>
     [Alias("Instance")]
     [Parameter(ParameterSetName = GenericName)]
@@ -116,61 +127,73 @@ private const string
     public string? InstanceName { get; set; }
 
     /// <summary>
-    ///   <b>-ReadOnlyIntent:</b> TODO
+    ///   <b>-ReadOnlyIntent:</b>
+    ///   Specifies that the client intends to perform only reads.
     /// </summary>
     [Alias("ReadOnly")]
     [Parameter]
     public SwitchParameter ReadOnlyIntent { get; set; }
 
     /// <summary>
-    ///   <b>-ClientName:</b> TODO
+    ///   <b>-ClientName:</b>
+    ///   Name of the client device.
     /// </summary>
     [Alias("Client")]
     [Parameter]
     [AllowNull, AllowEmptyString]
     public string? ClientName { get; set; }
 
     /// <summary>
-    ///   <b>-ApplicationName:</b> TODO
+    ///   <b>-ApplicationName:</b>
+    ///   Name of the client application.
     /// </summary>
     [Alias("Application")]
     [Parameter]
     [AllowNull, AllowEmptyString]
     public string? ApplicationName { get; set; }
 
     /// <summary>
-    ///   <b>-ConnectTimeout:</b> TODO
+    ///   <b>-ConnectTimeout:</b>
+    ///   Duration after which a connection attempt times out.
     /// </summary>
     [Alias("Timeout")]
     [Parameter]
     [ValidateNullOrTimeout]
     public TimeSpan? ConnectTimeout { get; set; }
 
     /// <summary>
-    ///   <b>-ExposeCredentialInConnectionString:</b> TODO
+    ///   <b>-ExposeCredentialInConnectionString:</b>
+    ///   Specifies that the credential used for authentication should be
+    ///   exposed in connections' ConnectionString property.
     /// </summary>
     [Parameter]
     public SwitchParameter ExposeCredentialInConnectionString { get; set; }
 
     /// <summary>
-    ///   <b>-Pooling:</b> TODO
+    ///   <b>-Pooling:</b>
+    ///   Specifies that connections may be pooled to reduce setup and teardown
+    ///   time.
     /// </summary>
     [Parameter]
     public SwitchParameter Pooling { get; set; }
 
     /// <summary>
-    ///   <b>-MultipleActiveResultSets:</b> TODO
+    ///   <b>-MultipleActiveResultSets:</b>
+    ///   Specifies that connections support execution of multiple batches
+    ///   concurrently, with limitations.
     /// </summary>
     [Alias("Mars")]
     [Parameter]
     public SwitchParameter MultipleActiveResultSets { get; set; }
 
     /// <summary>
-    ///   <b>-Frozen:</b> TODO
+    ///   <b>-Frozen:</b>
+    ///   Specifies that the created context should be frozen.
     /// </summary>
     [Parameter]
     public SwitchParameter Frozen { get; set; }
 
+    /// <inheritdoc/>
     protected override void ProcessRecord()
     {
         var context = Source?.Clone() ?? CreateContext();