Enhance and clarify documentation (#9803)

Author: potatoqualitee

public/Add-DbaAgDatabase.ps1

@@ -1,12 +1,12 @@
 function Add-DbaAgDatabase {
     <#
     .SYNOPSIS
-        Adds database(s) to an Availability Group on a SQL Server instance.
+        Adds databases to an Availability Group with automated backup, restore, and synchronization handling.
 
     .DESCRIPTION
-        Adds database(s) to an Availability Group on a SQL Server instance.
+        Adds databases to an Availability Group and handles the complete process from backup through synchronization. This command eliminates the manual steps typically required when expanding Availability Groups with new databases, automatically managing seeding modes, backup/restore operations, and replica synchronization.
 
-        After checking for prerequisites, the commands runs these five steps for every database:
+        The command executes a comprehensive five-step process for each database:
         * Step 1: Setting seeding mode if needed.
           - If -SeedingMode is used and the current seeding mode of the replica is not in the desired mode, the seeding mode of the replica is changed.
           - The seeding mode will not be changed back but stay in this mode.
@@ -21,11 +21,9 @@ function Add-DbaAgDatabase {
           - This step is skipped for those replicas, where the database is already joined to the Availability Group.
         * Step 5: Wait for the database to finish joining the Availability Group on the secondary replicas.
 
-        Use Test-DbaAvailabilityGroup with -AddDatabase to test if all prerequisites are met.
+        Use Test-DbaAvailabilityGroup with -AddDatabase to test if all prerequisites are met before running this command.
 
-        If you have special requirements for the setup for the database at the replicas,
-        perform the backup and restore part with Backup-DbaDatabase and Restore-DbaDatabase in advance.
-        Please make sure that the last log backup has been restored before running Add-DbaAgDatabase.
+        For custom backup and restore requirements, perform those operations with Backup-DbaDatabase and Restore-DbaDatabase in advance, ensuring the last log backup has been restored before running Add-DbaAgDatabase.
 
     .PARAMETER SqlInstance
         The primary replica of the Availability Group. Server version must be SQL Server version 2012 or higher.
@@ -562,4 +560,4 @@ function Add-DbaAgDatabase {
         }
         Write-Progress @progress -Completed
     }
-}
+}

public/Add-DbaAgListener.ps1

@@ -2,10 +2,14 @@
 function Add-DbaAgListener {
     <#
     .SYNOPSIS
-        Adds a listener to an availability group on a SQL Server instance.
+        Creates a network listener endpoint for an Availability Group to provide client connectivity
 
     .DESCRIPTION
-        Adds a listener to an availability group on a SQL Server instance.
+        Creates a network listener endpoint that provides a virtual network name and IP address for clients to connect to an Availability Group. The listener automatically routes client connections to the current primary replica, eliminating the need for applications to track which server is currently hosting the primary database.
+
+        This function supports both single-subnet and multi-subnet Availability Group configurations. You can specify static IP addresses for each subnet or use DHCP for automatic IP assignment. For multi-subnet deployments, specify multiple IP addresses and subnet masks to handle failover across geographically dispersed replicas.
+
+        Use this when setting up new Availability Groups or when adding listeners to existing groups that don't have client connectivity configured yet. Without a listener, applications must connect directly to replica server names, which breaks during failover scenarios.
 
     .PARAMETER SqlInstance
         The target SQL Server instance or instances. Server version must be SQL Server version 2012 or higher.

public/Add-DbaComputerCertificate.ps1

@@ -1,10 +1,12 @@
 function Add-DbaComputerCertificate {
     <#
     .SYNOPSIS
-        Adds a computer certificate - useful for older systems.
+        Imports X.509 certificates into the Windows certificate store on local or remote computers.
 
     .DESCRIPTION
-        Adds a computer certificate from a local or remote computer.
+        Imports X.509 certificates (including password-protected .pfx files with private keys) into the specified Windows certificate store on one or more computers. This function is essential for SQL Server TLS/SSL encryption setup, Availability Group certificate requirements, and Service Broker security configurations.
+
+        The function handles both certificate files from disk and certificate objects from the pipeline, supports remote installation via PowerShell remoting, and allows you to control import behavior through various flags like exportable/non-exportable private keys. By default, certificates are installed to the LocalMachine\My (Personal) store with exportable and persistent private keys, which is the standard location for SQL Server service certificates.
 
     .PARAMETER ComputerName
         The target SQL Server instance or instances. Defaults to localhost.

public/Add-DbaDbRoleMember.ps1

@@ -1,10 +1,10 @@
 function Add-DbaDbRoleMember {
     <#
     .SYNOPSIS
-        Adds a Database User to a database role for each instance(s) of SQL Server.
+        Adds database users or roles as members to database roles across SQL Server instances
 
     .DESCRIPTION
-        The Add-DbaDbRoleMember adds users in a database to a database role or roles for each instance(s) of SQL Server.
+        Manages database security by adding users or roles as members to database roles, automating what would otherwise require manual T-SQL commands or SQL Server Management Studio clicks. This function handles membership validation to ensure the user or role exists in the database before attempting to add them, and checks existing membership to prevent duplicate assignments. You can add multiple users to multiple roles across multiple databases and instances in a single operation, making it ideal for bulk security configuration or automated permission management workflows.
 
     .PARAMETER SqlInstance
         The target SQL Server instance or instances. This can be a collection and receive pipeline input to allow the function to be executed against multiple SQL Server instances.

public/Add-DbaExtendedProperty.ps1

@@ -1,12 +1,12 @@
 function Add-DbaExtendedProperty {
     <#
     .SYNOPSIS
-        Adds an extended property
+        Adds extended properties to SQL Server objects for metadata storage and documentation
 
     .DESCRIPTION
-        Adds an extended property
+        Creates custom metadata properties on SQL Server objects to store documentation, version information, business context, or compliance tags. Extended properties are stored in the database system catalogs and don't affect object performance but provide valuable context for DBAs managing complex environments.
 
-        This command works out of the box with databases but you can add extended properties from several different types of objects, including:
+        This command accepts piped input from any dbatools Get-Dba* command, making it easy to bulk-apply properties across multiple objects. You can add extended properties to databases directly or target specific object types, including:
 
         Aggregate
         Assembly

public/Add-DbaPfDataCollectorCounter.ps1

@@ -1,10 +1,10 @@
 function Add-DbaPfDataCollectorCounter {
     <#
     .SYNOPSIS
-        Adds a Performance Data Collector Counter.
+        Adds performance counters to existing Windows Performance Monitor Data Collector Sets for SQL Server monitoring.
 
     .DESCRIPTION
-        Adds a Performance Data Collector Counter.
+        Adds specific performance counters to existing Data Collector Sets within Windows Performance Monitor. This allows DBAs to customize their performance monitoring by adding SQL Server-specific counters like disk queue length, processor time, or SQL Server object counters to existing collection sets. The function modifies the Data Collector Set configuration and immediately applies the changes, so you can start collecting the additional performance metrics without recreating your monitoring setup.
 
     .PARAMETER ComputerName
         The target computer. Defaults to localhost.

public/Add-DbaRegServer.ps1

@@ -1,11 +1,10 @@
 function Add-DbaRegServer {
     <#
     .SYNOPSIS
-        Adds registered servers to SQL Server Central Management Server (CMS) or Local Server Groups
+        Registers SQL Server instances to Central Management Server or Local Server Groups in SSMS
 
     .DESCRIPTION
-        Adds registered servers to SQL Server Central Management Server (CMS) or Local Server Groups. If you need more flexibility, look into Import-DbaRegServer which
-        accepts multiple kinds of input and allows you to add reg servers from different CMSes.
+        Registers SQL Server instances as managed servers within SSMS, either to a Central Management Server (CMS) for enterprise-wide management or to Local Server Groups for personal organization. This allows DBAs to centrally organize and quickly connect to multiple SQL Server instances from SSMS without manually typing connection details each time. The function automatically creates server groups if they don't exist and supports various authentication methods including SQL Server, Windows, and Azure Active Directory. For importing existing registered servers from other sources, use Import-DbaRegServer instead.
 
     .PARAMETER SqlInstance
         The target SQL Server instance if a CMS is used

public/Add-DbaRegServerGroup.ps1

@@ -1,10 +1,10 @@
 function Add-DbaRegServerGroup {
     <#
     .SYNOPSIS
-        Adds registered server groups to SQL Server Central Management Server (CMS)
+        Creates organizational server groups within SQL Server Central Management Server (CMS)
 
     .DESCRIPTION
-        Adds registered server groups to SQL Server Central Management Server (CMS). If you need more flexibility, look into Import-DbaRegServer which accepts multiple kinds of input and allows you to add reg servers and groups from different CMS.
+        Creates new server groups in SQL Server Central Management Server to organize registered servers into logical hierarchies. This allows DBAs to group servers by environment, application, location, or any other classification system for easier management at scale. Supports nested group structures using backslash notation (Group\SubGroup) and automatically creates parent groups if they don't exist. If you need to import existing groups and servers from other sources, use Import-DbaRegServer instead.
 
     .PARAMETER SqlInstance
         The target SQL Server instance

public/Add-DbaReplArticle.ps1

@@ -1,10 +1,10 @@
 function Add-DbaReplArticle {
     <#
     .SYNOPSIS
-        Add an article configuration to a publication in a database on the SQL Server instance(s).
+        Adds a table or other database object as an article to an existing replication publication.
 
     .DESCRIPTION
-        Add an article configuration to a publication in a database on the SQL Server instance(s).
+        Adds a database object (typically a table) as an article to an existing SQL Server replication publication. Articles define which tables and data get replicated to subscribers. This function supports both transactional and merge replication publications, allowing you to expand replication topology without using SQL Server Management Studio. You can apply horizontal filters to replicate only specific rows, and customize schema options like indexes and statistics that get created on subscriber databases.
 
     .PARAMETER SqlInstance
         The SQL Server instance(s) for the publication.

public/Add-DbaServerRoleMember.ps1

@@ -1,10 +1,10 @@
 function Add-DbaServerRoleMember {
     <#
     .SYNOPSIS
-        Adds a login to a server-level role(s) for each instance(s) of SQL Server.
+        Adds logins or server roles to server-level roles for SQL Server security administration.
 
     .DESCRIPTION
-        Adds a login to a server-level role(s) for each instance(s) of SQL Server.
+        Grants server-level role membership to SQL logins or nests server roles within other server roles. Use this command when setting up security permissions, implementing role-based access control, or managing server-level privileges across multiple SQL Server instances. Supports both built-in roles (sysadmin, dbcreator, etc.) and custom server roles, so you don't have to manually assign permissions through SSMS or T-SQL scripts.
 
     .PARAMETER SqlInstance
         The target SQL Server instance or instances. This can be a collection and receive pipeline input to allow the function to be executed against multiple SQL Server instances.