Add QA test (#66)

* Add QA test

* Add pester 5 prepared QA tests

* Fix script analyzer rule quality checks

* Fix comment-based help

* Update commentbased help

* Fix default branch name

* Fix review comments at r1

* Fix code style formatting

* Update with more formatting

* Fix typo in parameter name and comment

* Fix more style things

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     `Required` or `Write`.
   - `Get-CompositeResourceParameterValidateSet` - Returns the array of values
     contained in the ValidateSet parameter attributes if it exists.
+- Added QA test to do some quality checks on the module code and change log.
 
 ### Changed
 
@@ -43,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     use with composite DSC resources.
   - Enabled the function to extract the comment block if it is not at the top
     of the script file to support composite resources.
+- Updated code to pass newly added quality checks.
 
 ### Fixed
 

build.yaml

@@ -65,7 +65,8 @@ Pester:
   ExcludeFromCodeCoverage:
     - Modules/DscResource.Common
   Script:
-  - tests/unit
+    - tests/QA
+    - tests/unit
   ExcludeTag:
   Tag:
   CodeCoverageThreshold: 80

source/Private/Copy-WikiFolder.ps1

@@ -3,6 +3,10 @@
         Copies any Wiki files from the module into the Wiki and optionally overwrite
         any existing files.
 
+    .DESCRIPTION
+        Copies any Wiki files from the module into the Wiki and optionally overwrite
+        any existing files.
+
     .PARAMETER Path
         The path to the output that was generated by New-DscResourceWikiPage.
 
@@ -12,6 +16,9 @@
     .PARAMETER WikiSourcePath
         The name of the folder that contains the source Wiki files.
 
+    .PARAMETER Force
+        If present, copies files forcefully, overwriting any existing files.
+
     .EXAMPLE
         Copy-WikiFolder -Path '.\output\WikiContent' -DestinationPath 'c:\repoName.wiki.git' -WikiSourcePath '.\source\WikiSource'
 

source/Private/Format-Text.ps1

@@ -2,8 +2,11 @@
     .SYNOPSIS
         Formats a string using predefined format options.
 
+    .DESCRIPTION
+        Formats a string using predefined format options.
+
     .PARAMETER Text
-        The string to format.
+        Specifies the string to format.
 
     .PARAMETER Format
         One or more predefined format options. The formatting is done in the

source/Private/Get-ClassAst.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Returns the AST for a single or all classes.
 
+    .DESCRIPTION
+        Returns the AST for a single or all classes.
+
     .PARAMETER ScriptFile
         The path to the source file that contain the class.
 
@@ -21,6 +24,7 @@
 function Get-ClassAst
 {
     [CmdletBinding()]
+    [OutputType([System.Collections.Generic.IEnumerable`1[System.Management.Automation.Language.Ast]])]
     param
     (
         [Parameter(Mandatory = $true)]

source/Private/Get-ClassResourceAst.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Returns the AST for a single or all DSC class resources.
 
+    .DESCRIPTION
+        Returns the AST for a single or all DSC class resources.
+
     .PARAMETER ScriptFile
         The path to the source file that contain the DSC class resource.
 

source/Private/Get-ClassResourceProperty.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Returns DSC class resource properties from the provided class or classes.
 
+    .DESCRIPTION
+        Returns DSC class resource properties from the provided class or classes.
+
     .PARAMETER SourcePath
         The path to the source folder (in which the child folder 'Classes' exist).
 

source/Private/Get-ConfigurationAst.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Returns the AST for a single or all configurations.
 
+    .DESCRIPTION
+        Returns the AST for a single or all configurations.
+
     .PARAMETER ScriptFile
         The path to the source file that contain the configuration.
 
@@ -25,6 +28,7 @@
 function Get-ConfigurationAst
 {
     [CmdletBinding()]
+    [OutputType([System.Collections.Generic.IEnumerable`1[System.Management.Automation.Language.Ast]])]
     param
     (
         [Parameter(Mandatory = $true)]

source/Private/Get-DscResourceHelpExampleContent.ps1

@@ -10,8 +10,8 @@
     .PARAMETER ExamplePath
         The path to the example file.
 
-    .PARAMETER ModulePath
-        The number of the example.
+    .PARAMETER ExampleNumber
+        The (order) number of the example.
 
     .EXAMPLE
         Get-DscResourceHelpExampleContent -ExamplePath 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1' -ExampleNumber 1

source/Private/Get-DscResourceSchemaPropertyContent.ps1

@@ -7,10 +7,14 @@
         Get-DscResourceSchemaPropertyContent is used to generate the parameter content
         for the wiki page.
 
-    .PARAMETER Attribute
+    .PARAMETER Property
         A hash table with properties that is returned by Get-MofSchemaObject in
         the property Attributes.
 
+    .PARAMETER UseMarkdown
+        If certain text should be output as markdown, for example values of the
+        hashtable property ValueMap.
+
     .EXAMPLE
         $content = Get-DscResourceSchemaPropertyContent -Property @(
                 @{

source/Private/Get-DscResourceWikiExampleContent.ps1

@@ -12,8 +12,8 @@
     .PARAMETER ExamplePath
         The path to the example file.
 
-    .PARAMETER ModulePath
-        The number of the example.
+    .PARAMETER ExampleNumber
+        The (order) number of the example.
 
     .EXAMPLE
         Get-DscResourceWikiExampleContent -ExamplePath 'C:\repos\NetworkingDsc\Examples\Resources\DhcpClient\1-DhcpClient_EnableDHCP.ps1' -ExampleNumber 1

source/Private/Get-TemporaryPath.ps1

@@ -8,6 +8,11 @@
         on Windows OS, '/tmp' when run in Linux and $ENV:TMPDIR when
         run on MacOS.
 
+    .EXAMPLE
+        Get-TemporaryPath
+
+        Get the temporary path (which will differ between operating system).
+
     .NOTES
         We use Get-Variable to determine if the OS specific variables are
         defined so that we can mock these during testing. We also use Get-Item

source/Private/Invoke-Git.ps1

@@ -1,6 +1,9 @@
 <#
     .SYNOPSIS
-        Invokes the git command.
+        Invokes a git command.
+
+    .DESCRIPTION
+        Invokes a git command with command line arguments.
 
     .PARAMETER WorkingDirectory
         The path to the git working directory.

source/Private/New-DscClassResourceWikiPage.ps1

@@ -20,6 +20,9 @@
         The path to the root of the built DSC resource module, e.g.
         'output/MyResource/1.0.0'.
 
+    .PARAMETER Force
+        Overwrites any existing file when outputting the generated content.
+
     .EXAMPLE
         New-DscClassResourceWikiPage `
             -SourcePath C:\repos\MyResource\source `
@@ -30,6 +33,7 @@
 #>
 function New-DscClassResourceWikiPage
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Private/New-DscMofResourceWikiPage.ps1

@@ -20,6 +20,9 @@
         The path to the root of the built DSC resource module, e.g.
         'output/MyResource/1.0.0'.
 
+    .PARAMETER Force
+        Overwrites any existing file when outputting the generated content.
+
     .EXAMPLE
         New-DscMofResourceWikiPage `
             -SourcePath C:\repos\MyResource\source `
@@ -30,6 +33,8 @@
 #>
 function New-DscMofResourceWikiPage
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Private/New-TempFolder.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Creates a new temporary folder with a random name.
 
+    .DESCRIPTION
+        Creates a new temporary folder with a random name.
+
     .EXAMPLE
         New-TempFolder
 
@@ -15,6 +18,7 @@
 #>
 function New-TempFolder
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     [OutputType([System.IO.DirectoryInfo])]
     param

source/Private/New-WikiFooter.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Creates the Wiki footer file if one does not already exist.
 
+    .DESCRIPTION
+        Creates the Wiki footer file if one does not already exist.
+
     .PARAMETER Path
         The path for the Wiki footer file.
 
@@ -15,6 +18,7 @@
 #>
 function New-WikiFooter
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Private/New-WikiSidebar.ps1

@@ -2,6 +2,9 @@
     .SYNOPSIS
         Creates the Wiki side bar file from the list of markdown files in the path.
 
+    .DESCRIPTION
+        Creates the Wiki side bar file from the list of markdown files in the path.
+
     .PARAMETER ModuleName
         The name of the module to generate a new Wiki Sidebar file for.
 
@@ -20,6 +23,7 @@
 #>
 function New-WikiSidebar
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Private/Test-PropertyMemberAst.ps1

@@ -11,6 +11,18 @@
         The Abstract Syntax Tree (AST) for class-based DSC resource property.
         The passed value must be an AST of the type 'PropertyMemberAst'.
 
+    .PARAMETER IsKey
+        Specifies if the parameter is expected to have the type qualifier Key.
+
+    .PARAMETER IsMandatory
+        Specifies if the parameter is expected to have the type qualifier Mandatory.
+
+    .PARAMETER IsWrite
+        Specifies if the parameter is expected to have the type qualifier Write.
+
+    .PARAMETER IsRead
+        Specifies if the parameter is expected to have the type qualifier Read.
+
     .EXAMPLE
         Test-PropertyMemberAst -IsKey -Ast {
             [DscResource()]

source/Public/New-DscResourcePowerShellHelp.ps1

@@ -99,6 +99,7 @@
 #>
 function New-DscResourcePowerShellHelp
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Public/New-DscResourceWikiPage.ps1

@@ -21,6 +21,9 @@
         The path to the root of the built DSC resource module, e.g.
         'output/MyResource/1.0.0'.
 
+    .PARAMETER Force
+        Overwrites any existing file when outputting the generated content.
+
     .EXAMPLE
         New-DscResourceWikiPage `
             -SourcePath C:\repos\MyResource\source `
@@ -31,6 +34,7 @@
 #>
 function New-DscResourceWikiPage
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Public/Publish-WikiContent.ps1

@@ -33,6 +33,11 @@
     .PARAMETER GitUserName
         The user name to use for the Git commit.
 
+    .PARAMETER GlobalCoreAutoCrLf
+        Specifies how line breaks should be handled when cloning the
+        GitHub wiki repository. Valid values are 'true', 'false', or
+        'input'.
+
     .EXAMPLE
         Publish-WikiContent `
             -Path '.\output\WikiContent' `

source/Public/Set-WikiModuleVersion.ps1

@@ -19,6 +19,7 @@
 #>
 function Set-WikiModuleVersion
 {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
     [CmdletBinding()]
     param
     (

source/Public/Split-ModuleVersion.ps1

@@ -3,8 +3,12 @@
         This function parses a module version string as returns a PSCustomObject
         which each of the module version's parts.
 
+    .DESCRIPTION
+        This function parses a module version string as returns a PSCustomObject
+        which each of the module version's parts.
+
     .PARAMETER ModuleVersion
-        The module to parse.
+        The module version for which to return the module version's parts.
 
     .EXAMPLE
         Split-ModuleVersion -ModuleVersion '1.15.0-pr0224-0022+Sha.47ae45eb'