Merge pull request #371 from fflaten/help-tests

Rewrite help and common function tests
maester365 · Jul 21, 2024 · 1e6dfeb · 1e6dfeb
2 parents 676400c + f6de490
commit 1e6dfeb
Show file tree

Hide file tree

Showing 107 changed files with 593 additions and 494 deletions.
diff --git a/powershell/public/Add-MtTestResultDetail.ps1 b/powershell/public/Add-MtTestResultDetail.ps1
@@ -30,9 +30,10 @@
 
     This example shows how to use the Add-MtTestResultDetail function to add rich markdown content to the test results with deep links to the admin portal.
 
+.LINK
+    https://maester.dev/docs/commands/Add-MtTestResultDetail
 #>
-
-Function Add-MtTestResultDetail {
+function Add-MtTestResultDetail {
     [CmdletBinding()]
     param(
         # Brief description of what this test is checking.
@@ -66,9 +67,11 @@ Function Add-MtTestResultDetail {
         [ValidateSet('NotConnectedAzure', 'NotConnectedExchange', 'NotDotGovDomain', 'NotLicensedEntraIDP1', 'NotConnectedSecurityCompliance',
             'NotLicensedEntraIDP2', 'NotLicensedEntraIDGovernance', 'NotLicensedEntraWorkloadID', "LicensedEntraIDPremium", 'NotSupported', 'Custom'
         )]
+        # Common reasons for why the test was skipped.
         [string] $SkippedBecause,
 
         [Parameter(Mandatory = $false)]
+        # A custom reason for why the test was skipped. Requires `-SkippedBecause Custom`.
         [string] $SkippedCustomReason
     )
 

diff --git a/powershell/public/Clear-MtDnsCache.ps1 b/powershell/public/Clear-MtDnsCache.ps1
@@ -11,6 +11,9 @@
     Clear-MtDnsCache
 
     This example clears the cache of all DNS lookups.
+
+.LINK
+    https://maester.dev/docs/commands/Clear-MtDnsCache
 #>
 function Clear-MtDnsCache {
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification='Setting module level variable')]

diff --git a/powershell/public/Clear-MtGraphCache.ps1 b/powershell/public/Clear-MtGraphCache.ps1
@@ -16,6 +16,9 @@
     Clear-MtGraphCache
 
     This example clears the cache of all Graph API calls.
+
+.LINK
+    https://maester.dev/docs/commands/Clear-MtGraphCache
 #>
 function Clear-MtGraphCache {
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification='Setting module level variable')]

diff --git a/powershell/public/Compare-MtTestResult.ps1 b/powershell/public/Compare-MtTestResult.ps1
@@ -12,15 +12,21 @@
         PriorTest = (Get-Content .\test-results\TestResults-2024-05-20-182925.json | ConvertFrom-Json)
     }
     Compare-MtTestResult @tests
+
+.LINK
+    https://maester.dev/docs/commands/Compare-MtTestResult
 #>
 function Compare-MtTestResult {
     [CmdletBinding()]
     param (
         [Parameter(ParameterSetName="Directory",Position=0,Mandatory=$true)]
+        # Path to folder where test results are located. The two newest results will be compared.
         $BaseDir,
         [Parameter(ParameterSetName="Files",Position=0,Mandatory=$true)]
+        # Path to the previous test result JSON-file to be used as a reference.
         $PriorTest,
         [Parameter(ParameterSetName="Files",Position=1,Mandatory=$true)]
+        # Path to the newer test result JSON-file to be used as the current result.
         $NewTest
     )
 

diff --git a/powershell/public/Connect-Maester.ps1 b/powershell/public/Connect-Maester.ps1
@@ -45,9 +45,11 @@
    Connect-Maester -Privileged
 
    Connects to Microsoft Graph with additional privileged scopes such as **RoleEligibilitySchedule.ReadWrite.Directory** that are required for querying global admin roles in Privileged Identity Management.
-#>
 
-Function Connect-Maester {
+.LINK
+    https://maester.dev/docs/commands/Connect-Maester
+#>
+function Connect-Maester {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Colors are beautiful')]
    [Alias("Connect-MtGraph", "Connect-MtMaester")]
    [CmdletBinding()]

diff --git a/powershell/public/Disconnect-Maester.ps1 b/powershell/public/Disconnect-Maester.ps1
@@ -19,9 +19,10 @@
  .Example
     Disconnect-MtMaester
 
+.LINK
+    https://maester.dev/docs/commands/Disconnect-Maester
 #>
-
-Function Disconnect-Maester {
+function Disconnect-Maester {
    [Alias("Disconnect-MtMaester", "Disconnect-MtGraph")]
    [CmdletBinding()]
    param()

diff --git a/powershell/public/Get-MtAuthenticationMethodPolicyConfig.ps1 b/powershell/public/Get-MtAuthenticationMethodPolicyConfig.ps1
@@ -7,13 +7,17 @@
 
 .EXAMPLE
     Get-MtAuthenticationMethodPolicyConfig -State Enabled
+
+.LINK
+    https://maester.dev/docs/commands/Get-MtAuthenticationMethodPolicyConfig
 #>
 function Get-MtAuthenticationMethodPolicyConfig {
 
     [CmdletBinding()]
     param(
         [Parameter(Mandatory = $false)]
         [ValidateSet("Enabled", "Disabled")]
+        # Only return methods in the spcecified state. Can be Enabled or Disabled.
         [string]$State
     )
 

diff --git a/powershell/public/Get-MtConditionalAccessPolicy.ps1 b/powershell/public/Get-MtConditionalAccessPolicy.ps1
@@ -3,12 +3,15 @@
   Returns all the conditional access policies in the tenant.
 
  .Description
+  Returns all the conditional access policies in the tenant.
 
  .Example
   Get-MtConditionalAccessPolicy
-#>
 
-Function Get-MtConditionalAccessPolicy {
+.LINK
+    https://maester.dev/docs/commands/Get-MtConditionalAccessPolicy
+#>
+function Get-MtConditionalAccessPolicy {
   [CmdletBinding()]
   param()
 

diff --git a/powershell/public/Get-MtGraphScope.ps1 b/powershell/public/Get-MtGraphScope.ps1
@@ -24,9 +24,11 @@
     Connect-MgGraph -Scopes (Get-MtGraphScope -PrivilegedScopes)
 
     Connects to Microsoft Graph with the required scopes to run Maester for all tests, including those requiring read write APIs.
-#>
 
-Function Get-MtGraphScope {
+.LINK
+    https://maester.dev/docs/commands/Get-MtGraphScope
+#>
+function Get-MtGraphScope {
 
     [CmdletBinding()]
     param(

diff --git a/powershell/public/Get-MtGroupMember.ps1 b/powershell/public/Get-MtGroupMember.ps1
@@ -3,23 +3,28 @@
   Returns all the members of the specific group ID.
 
  .Description
+  Returns all the members of the specific group ID.
 
  .Example
   Get-MtGroupMember
-#>
 
-Function Get-MtGroupMember {
+.LINK
+    https://maester.dev/docs/commands/Get-MtGroupMember
+#>
+function Get-MtGroupMember {
   [CmdletBinding()]
   param(
     [Parameter(Position=0,mandatory=$true)]
-    [guid]$groupId,
+    # ID for the Entra group to return members for.
+    [guid]$GroupId,
+    # Include indirect members through nested groups.
     [switch]$Recursive
   )
 
   Write-Verbose -Message "Getting group members."
 
   $members = @()
-  $members += Invoke-MtGraphRequest -RelativeUri "groups/$groupId/members" -ApiVersion v1.0
+  $members += Invoke-MtGraphRequest -RelativeUri "groups/$GroupId/members" -ApiVersion v1.0
 
   if(-not $recursive){
     return $members
@@ -28,7 +33,7 @@ Function Get-MtGroupMember {
   $members | Where-Object {`
     $_.'@odata.type' -eq "#microsoft.graph.group"
   } | ForEach-Object {`
-    $members += Get-MtGroupMember -groupId $_.id -Recursive
+    $members += Get-MtGroupMember -GroupId $_.id -Recursive
   }
 
   return $members

diff --git a/powershell/public/Get-MtLicenseInformation.ps1 b/powershell/public/Get-MtLicenseInformation.ps1
@@ -10,6 +10,9 @@
 
 .EXAMPLE
     Get-MtLicenseInformation -Product EntraID
+
+.LINK
+    https://maester.dev/docs/commands/Get-MtLicenseInformation
 #>
 function Get-MtLicenseInformation {
     [OutputType([string])]

diff --git a/powershell/public/Get-MtRole.ps1 b/powershell/public/Get-MtRole.ps1
@@ -3,16 +3,19 @@
   Returns all the role definitions in the tenant.
 
  .Description
+  Returns all the role definitions in the tenant.
 
  .Parameter CisaHighlyPrivilegedRoles
   Filters the returned roles to only those described
   by CISA as highly privieleged.
 
  .Example
   Get-MtRole
-#>
 
-Function Get-MtRole {
+.LINK
+    https://maester.dev/docs/commands/Get-MtRole
+#>
+function Get-MtRole {
   [CmdletBinding()]
   param(
     [switch]$CisaHighlyPrivilegedRoles

diff --git a/powershell/public/Get-MtRoleMember.ps1 b/powershell/public/Get-MtRoleMember.ps1
@@ -35,9 +35,10 @@
 
   Returns all the currently active members of the role with the specified RoleId.
 
+.LINK
+    https://maester.dev/docs/commands/Get-MtRoleMember
 #>
-
-Function Get-MtRoleMember {
+function Get-MtRoleMember {
   [CmdletBinding(DefaultParameterSetName = "RoleName")]
   param(
     # The name of the role to get members for.
@@ -117,7 +118,7 @@ Function Get-MtRoleMember {
       $groups = $assignments | Where-Object { $_.'@odata.type' -eq "#microsoft.graph.group" }
       $groups | ForEach-Object {`
           #5/10/2024 - Entra ID Role Enabled Security Groups do not currently support nesting
-          $assignments += Get-MtGroupMember -groupId $_.id
+          $assignments += Get-MtGroupMember -GroupId $_.id
       }
     }
 

diff --git a/powershell/public/Get-MtUser.ps1 b/powershell/public/Get-MtUser.ps1
@@ -19,6 +19,8 @@
     Get-MtUser -Count 5 -UserType Member
     # Get 5 Member users from the tenant.
 
+.LINK
+    https://maester.dev/docs/commands/Get-MtUser
 #>
 function Get-MtUser {
     [OutputType([System.Collections.ArrayList])]

diff --git a/powershell/public/Get-MtUserAuthenticationMethod.ps1 b/powershell/public/Get-MtUserAuthenticationMethod.ps1
@@ -20,8 +20,11 @@
   Get-MtUserAuthenticationMethod -UserId 'john@contoso.com'
 
   # Get the authentication methods for the specified user
+
+.LINK
+    https://maester.dev/docs/commands/Get-MtUserAuthenticationMethod
 #>
-Function Get-MtUserAuthenticationMethod {
+function Get-MtUserAuthenticationMethod {
   [CmdletBinding()]
   param(
     # The GUID or user principal name of the user to get Authentication Methods for.

diff --git a/powershell/public/Get-MtUserAuthenticationMethodInfoByType.ps1 b/powershell/public/Get-MtUserAuthenticationMethodInfoByType.ps1
@@ -16,9 +16,11 @@
     $authMethod | Get-MtUserAuthenticationMethodInfoByType
 
     # Returns the DisplayName and IsMfa metadata for the authentication methods registered by the specified user.
-#>
 
-Function Get-MtUserAuthenticationMethodInfoByType {
+.LINK
+    https://maester.dev/docs/commands/Get-MtUserAuthenticationMethodInfoByType
+#>
+function Get-MtUserAuthenticationMethodInfoByType {
 
     [CmdletBinding()]
     param(

diff --git a/powershell/public/Invoke-Maester.ps1 b/powershell/public/Invoke-Maester.ps1
@@ -70,9 +70,11 @@ Invoke-Maester -PesterConfiguration $configuration
 
 ```
 Runs all the Pester tests in the EIDSCA folder.
-#>
 
-Function Invoke-Maester {
+.LINK
+    https://maester.dev/docs/commands/Invoke-Maester
+#>
+function Invoke-Maester {
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Justification = 'Colors are beautiful')]
     [Alias("Invoke-MtMaester")]
     [CmdletBinding()]

diff --git a/powershell/public/Invoke-MtGraphRequest.ps1 b/powershell/public/Invoke-MtGraphRequest.ps1
@@ -16,13 +16,14 @@
     :::
 
  .Example
-
     Invoke-MtGraph -RelativeUri "users" -Filter "displayName eq 'John Doe'" -Select "displayName" -Top 10
 
     Get all users with a display name of "John Doe" and return the first 10 results.
 
+.LINK
+    https://maester.dev/docs/commands/Invoke-MtGraphRequest
 #>
-Function Invoke-MtGraphRequest {
+function Invoke-MtGraphRequest {
     [CmdletBinding()]
     param(
         # Graph endpoint such as "users".

diff --git a/powershell/public/Send-MtMail.ps1 b/powershell/public/Send-MtMail.ps1
@@ -20,9 +20,11 @@
     Send-MtMail -MaesterResults $MaesterResults -Recipient john@contoso.com, sam@contoso.com -Subject 'Maester Results' -TestResultsUri "https://github.com/contoso/maester/runs/123456789"
 
     Sends an email with the summary of the Maester test results to two users along with the link to the detailed test results.
-#>
 
-Function Send-MtMail {
+.LINK
+    https://maester.dev/docs/commands/Send-MtMail
+#>
+function Send-MtMail {
     [CmdletBinding()]
     param(
         # The Maester test results returned from `Invoke-Pester -PassThru | ConvertTo-MtMaesterResult`

diff --git a/powershell/public/Send-MtTeamsMessage.ps1 b/powershell/public/Send-MtTeamsMessage.ps1
@@ -20,9 +20,11 @@
     Send-MtTeamsMessage -MaesterResults $MaesterResults -TeamId '00000000-0000-0000-0000-000000000000' -TeamChannelId '19%3A00000000000000000000000000000000%40thread.tacv2' -Subject 'Maester Results' -TestResultsUri "https://github.com/contoso/maester/runs/123456789"
 
     Sends an Adaptive Card in a Teams Channel with the summary of the Maester test results to the specified channel along with the link to the detailed test results.
-#>
 
-Function Send-MtTeamsMessage {
+.LINK
+    https://maester.dev/docs/commands/Send-MtTeamsMessage
+#>
+function Send-MtTeamsMessage {
     [CmdletBinding()]
     param(
         # The Maester test results returned from `Invoke-Pester -PassThru | ConvertTo-MtMaesterResult`

diff --git a/powershell/public/Test-MtAppManagementPolicyEnabled.ps1 b/powershell/public/Test-MtAppManagementPolicyEnabled.ps1
@@ -7,9 +7,11 @@
 
  .Example
   Test-MtAppManagementPolicyEnabled
-#>
 
-Function Test-MtAppManagementPolicyEnabled {
+.LINK
+    https://maester.dev/docs/commands/Test-MtAppManagementPolicyEnabled
+#>
+function Test-MtAppManagementPolicyEnabled {
   [CmdletBinding()]
   [OutputType([bool])]
   param()

diff --git a/powershell/public/Test-MtCaAllAppsExists.ps1 b/powershell/public/Test-MtCaAllAppsExists.ps1
@@ -18,15 +18,17 @@
   Test-MtCaAllAppsExists -SkipCheckAllUsers
 
   Returns true if at least one conditional access policy exists that targets all cloud apps and all users, but skips the check for all users.
-#>
 
-Function Test-MtCaAllAppsExists {
+.LINK
+    https://maester.dev/docs/commands/Test-MtCaAllAppsExists
+#>
+function Test-MtCaAllAppsExists {
   [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns', '', Justification = 'Exists is not a plurality')]
   [CmdletBinding()]
   [OutputType([bool])]
   param (
-
     [Parameter(Position = 0)]
+    # Do not check for All Users target in policy.
     [switch] $SkipCheckAllUsers = $false
   )
 

diff --git a/powershell/public/Test-MtCaApplicationEnforcedRestriction.ps1 b/powershell/public/Test-MtCaApplicationEnforcedRestriction.ps1
@@ -10,9 +10,11 @@
 
  .Example
   Test-MtCaApplicationEnforcedRestriction
-#>
 
-Function Test-MtCaApplicationEnforcedRestriction {
+.LINK
+    https://maester.dev/docs/commands/Test-MtCaApplicationEnforcedRestriction
+#>
+function Test-MtCaApplicationEnforcedRestriction {
     [CmdletBinding()]
     [OutputType([bool])]
     param ()

diff --git a/powershell/public/Test-MtCaBlockLegacyExchangeActiveSyncAuthentication.ps1 b/powershell/public/Test-MtCaBlockLegacyExchangeActiveSyncAuthentication.ps1
@@ -11,9 +11,11 @@
 
  .Example
   Test-MtCaBlockLegacyExchangeActiveSyncAuthentication
-#>
 
-Function Test-MtCaBlockLegacyExchangeActiveSyncAuthentication {
+.LINK
+    https://maester.dev/docs/commands/Test-MtCaBlockLegacyExchangeActiveSyncAuthentication
+#>
+function Test-MtCaBlockLegacyExchangeActiveSyncAuthentication {
     [CmdletBinding()]
     [OutputType([bool])]
     param ()