docs: fill in comment-based help gaps across 11 functions

PiHoleShell/Private/Misc.ps1

@@ -137,6 +137,28 @@ function ConvertTo-PiHoleFriendlyErrorMessage {
 }
 
 function Remove-PiHoleCurrentAuthSession {
+    <#
+.SYNOPSIS
+Delete session
+
+.DESCRIPTION
+Deletes the session identified by the given Sid. This is the internal best-effort logout every
+other function in this module calls automatically from its own finally block when it finishes -
+it never produces output, even on failure (a warning only). Shown here for completeness since it
+is still a publicly exported function, not because you need to call it yourself.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Sid
+The session ID to delete, as returned when logging in
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.EXAMPLE
+Remove-PiHoleCurrentAuthSession -PiHoleServer "http://pihole.domain.com:8080" -Sid $Sid
+    #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "", Justification = "It removes sessions from PiHole only")]
     [CmdletBinding()]
     param (

PiHoleShell/Public/Authentication/Get-PiHoleCurrentAuthSession.ps1

@@ -1,7 +1,11 @@
 function Get-PiHoleCurrentAuthSession {
     <#
 .SYNOPSIS
-List of all current sessions including their validity and further information about the client such as the IP address and user agent.
+List of all current sessions
+
+.DESCRIPTION
+List of all current sessions including their validity and further information about the client
+such as the IP address and user agent.
 
 .PARAMETER PiHoleServer
 The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"

PiHoleShell/Public/Authentication/Remove-PiHoleAuthSession.ps1

@@ -1,7 +1,11 @@
 function Remove-PiHoleAuthSession {
     <#
 .SYNOPSIS
-Using this endpoint, a session can be deleted by its ID.
+Delete session by ID
+
+.DESCRIPTION
+Deletes a session by its ID, as shown by Get-PiHoleCurrentAuthSession, rather than the caller's
+own current session.
 
 .PARAMETER PiHoleServer
 The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
@@ -12,8 +16,11 @@ The API Password you generated from your PiHole server
 .PARAMETER IgnoreSsl
 Ignore SSL when interacting with the PiHole API
 
+.PARAMETER Id
+The ID of the session to delete, as shown by Get-PiHoleCurrentAuthSession
+
 .EXAMPLE
-Get-PiHoleCurrentAuthSession -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+Remove-PiHoleAuthSession -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -Id 3
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '', Justification = 'Does not change state')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]

PiHoleShell/Public/DnsControl/Set-PiHoleDnsBlocking.ps1

@@ -21,6 +21,9 @@ True or False, if you set it to False when Blocking was set to true, it will dis
 .PARAMETER TimeInSeconds
 How long the opposite setting should last, in seconds
 
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
 .PARAMETER RawOutput
 This will dump the response instead of the formatted object
 

PiHoleShell/Public/GroupManagement/Get-PiHoleGroup.ps1

@@ -3,6 +3,30 @@ function Get-PiHoleGroup {
 .SYNOPSIS
 Get groups
 
+.DESCRIPTION
+Returns all groups configured on your Pi-hole. Lists and clients can be assigned to groups to
+apply blocking rules selectively rather than globally.
+
+.PARAMETER PiHoleServer
+The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"
+
+.PARAMETER Password
+The API Password you generated from your PiHole server
+
+.PARAMETER GroupName
+The name of a specific group to return. If omitted, every group is returned
+
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
+.PARAMETER RawOutput
+This will dump the response instead of the formatted object
+
+.EXAMPLE
+Get-PiHoleGroup -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password"
+
+.EXAMPLE
+Get-PiHoleGroup -PiHoleServer "http://pihole.domain.com:8080" -Password "your-app-password" -GroupName "Kids"
     #>
     [CmdletBinding(HelpUri = 'https://ftl.pi-hole.net/master/docs/#get-/groups/-name-')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingPlainTextForPassword", "Password")]

PiHoleShell/Public/ListManagement/Search-PiHoleListDomain.ps1

@@ -1,7 +1,10 @@
 function Search-PiHoleListDomain {
     <#
 .SYNOPSIS
-https://ftl.pi-hole.net/master/docs/#get-/search/-domain-
+Search domains in Pi-hole's lists
+
+.DESCRIPTION
+Searches Pi-hole's allow/deny lists for a domain, returning which list(s) it was found in.
 
 .PARAMETER PiHoleServer
 The URL to the PiHole Server, for example "http://pihole.domain.com:8080", or "http://192.168.1.100"

PiHoleShell/Public/Metrics/Get-PiHoleStatsQueryType.ps1

@@ -2,6 +2,8 @@ function Get-PiHoleStatsQueryType {
     <#
 .SYNOPSIS
 Get query types
+
+.DESCRIPTION
 Request a breakdown of query types (A, AAAA, ...)
 
 .PARAMETER PiHoleServer

PiHoleShell/Public/Metrics/Get-PiHoleStatsRecentBlocked.ps1

@@ -1,6 +1,9 @@
 function Get-PiHoleStatsRecentBlocked {
     <#
 .SYNOPSIS
+Get most recently blocked domain
+
+.DESCRIPTION
 Request most recently blocked domain
 
 .PARAMETER PiHoleServer
@@ -12,6 +15,9 @@ The API Password you generated from your PiHole server
 .PARAMETER MaxResult
 How many results should be returned
 
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
 .PARAMETER RawOutput
 This will dump the response instead of the formatted object
 

PiHoleShell/Public/Metrics/Get-PiHoleStatsSummary.ps1

@@ -2,6 +2,8 @@ function Get-PiHoleStatsSummary {
     <#
 .SYNOPSIS
 Get overview of Pi-hole activity
+
+.DESCRIPTION
 Request various query, system, and FTL properties
 
 .PARAMETER PiHoleServer

PiHoleShell/Public/Metrics/Get-PiHoleStatsTopClient.ps1

@@ -2,6 +2,8 @@ function Get-PiHoleStatsTopClient {
     <#
 .SYNOPSIS
 Get top clients
+
+.DESCRIPTION
 Request the top clients (by query count)
 
 .PARAMETER PiHoleServer
@@ -16,6 +18,9 @@ How many results should be returned
 .PARAMETER Blocked
 If true, returns top clients by blocked queries instead of total queries
 
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
 .PARAMETER RawOutput
 This will dump the response instead of the formatted object
 

PiHoleShell/Public/Metrics/Get-PiHoleStatsTopDomain.ps1

@@ -2,6 +2,8 @@ function Get-PiHoleStatsTopDomain {
     <#
 .SYNOPSIS
 Get top domains
+
+.DESCRIPTION
 Request the top domains (by query count)
 
 .PARAMETER PiHoleServer
@@ -16,6 +18,9 @@ How many results should be returned
 .PARAMETER Blocked
 If true, returns top domains by blocked queries instead of total queries
 
+.PARAMETER IgnoreSsl
+Set to $true to skip SSL certificate validation
+
 .PARAMETER RawOutput
 This will dump the response instead of the formatted object
 

README.md

@@ -120,7 +120,7 @@ See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every fu
 | `Add-PiHoleList` | Add a new list |
 | `Get-PiHoleList` | Get lists |
 | `Remove-PiHoleList` | Remove a list |
-| `Search-PiHoleListDomain` | _No description yet_ |
+| `Search-PiHoleListDomain` | Search domains in Pi-hole's lists |
 | `Update-PiHoleList` | Update a list |
 
 ### Domain Management
@@ -153,11 +153,11 @@ See [docs/EXAMPLES.md](docs/EXAMPLES.md) for real, captured output from every fu
 | `Get-PiHoleStatsDatabaseTopDomain` | Get top domains (long-term database) |
 | `Get-PiHoleStatsDatabaseUpstream` | Get metrics about Pi-hole's upstream destinations (long-term database) |
 | `Get-PiHoleStatsQuerySuggestions` | Get query filter suggestions |
-| `Get-PiHoleStatsQueryType` | Get query types Request a breakdown of query types (A, AAAA, ...) |
-| `Get-PiHoleStatsRecentBlocked` | Request most recently blocked domain |
-| `Get-PiHoleStatsSummary` | Get overview of Pi-hole activity Request various query, system, and FTL properties |
-| `Get-PiHoleStatsTopClient` | Get top clients Request the top clients (by query count) |
-| `Get-PiHoleStatsTopDomain` | Get top domains Request the top domains (by query count) |
+| `Get-PiHoleStatsQueryType` | Get query types |
+| `Get-PiHoleStatsRecentBlocked` | Get most recently blocked domain |
+| `Get-PiHoleStatsSummary` | Get overview of Pi-hole activity |
+| `Get-PiHoleStatsTopClient` | Get top clients |
+| `Get-PiHoleStatsTopDomain` | Get top domains |
 | `Get-PiHoleStatsUpstream` | Get metrics about Pi-hole's upstream destinations |
 
 ### Configuration & Diagnostics
@@ -207,8 +207,8 @@ Session handling is automatic for every command above, but these are available f
 |---|---|
 | `Get-PiHoleAuthStatus` | Check if authentication is required |
 | `Get-PiHoleAuthTotp` | Suggest new TOTP credentials |
-| `Get-PiHoleCurrentAuthSession` | List of all current sessions including their validity and further information about the client such as the IP address and user agent. |
-| `Remove-PiHoleAuthSession` | Using this endpoint, a session can be deleted by its ID. |
+| `Get-PiHoleCurrentAuthSession` | List of all current sessions |
+| `Remove-PiHoleAuthSession` | Delete session by ID |
 <!-- COMMAND-REFERENCE:END -->
 
 ## Testing