Refine documentation structure and enhance clarity in copilot instructions

Author: johlju

.github/copilot-instructions.md

@@ -4,23 +4,50 @@ Assume that the word "command" references to a public command, the word
 "function" references to a private function, and the word "resource"
 references a Desired State Configuration (DSC) class-based resource.
 
+## Public commands
+
 PowerShell commands that should be public should always have its separate
-script file and the the command name as the file name with the .ps1 extension,
+script file and the command name as the file name with the .ps1 extension,
 these files shall always be placed in the folder source/Public.
 
 Public commands may use private functions to move out logic that can be
 reused by other public commands, so move out any logic that can be deemed
-reusable. Private functions should always have its separate script file and
-the the function name as the file name with the .ps1 extension, these files
+reusable.
+
+## Private functions
+
+Private functions should always have its separate script file and
+the function name as the file name with the .ps1 extension, these files
 shall always be placed in the folder source/Private.
 
-Comment-based help should be added to each public command and private functions.
-The comment-based help should always be before the function-statement. Each
-comment-based help keyword should be indented with 4 spaces and each keywords
-text should be indented 8 spaces. The text for keyword .DESCRIPTION should
-be descriptive and must have a length greater than 40 characters. A comment-based
-help must have at least one example, but preferably more examples to showcase
-all possible parameter sets and different parameter combinations.
+## Desired State Configuration (DSC) class-based resource
+
+Desired State Configuration (DSC) class-based resource should always have
+its separate script file and the resource class name as the file name with
+the .ps1 extension, these files shall always be placed in the folder
+source/Classes.
+
+## Comment-based help
+
+Comment-based help should always be before the function-statement for each
+public command and private function, and before the class-statement for each
+class-based resource. Comment-based help should always be in the format of
+a comment block and at least use the keywords: .SYNOPSIS, .DESCRIPTION,
+.PARAMETER, .EXAMPLE, and .NOTES.
+
+Each comment-based help keyword should be indented with 4 spaces and each
+keyword's text should be indented 8 spaces.
+
+The text for keyword .DESCRIPTION should be descriptive and must have a
+length greater than 40 characters. The .SYNOPSIS keyword text should be
+a short description of the public command, private function, or class-based
+resource.
+
+A comment-based help must have at least one example, but preferably more
+examples to showcase all possible parameter sets and different parameter
+combinations.
+
+## Localization
 
 All message strings for Write-Debug, Write-Verbose, Write-Error, Write-Warning
 and other error messages in public commands and private functions should be
@@ -34,18 +61,23 @@ Always assume that all localized string keys have already been assigned to
 the variable $script:localizedData.
 
 For class-based resource you should always add a localized strings in a
-separate file the folder source\en-US. The strings file for For class-based
-resource should be named using the resource's name and suffixed with `.strings.psd1`.
-Localized string key names should always never be prefixed with anything but
-use underscore as word separator. Always assume that all localized string
-keys for a class-based resource already have been assigned to the variable
-`$this.localizedData`.
+separate file the folder source\en-US. The strings file for a class-based
+resource should be named to exactly match the resource class name with the
+suffix `.strings.psd1`.
+Localized string key names should never be prefixed with anything but
+use underscore as word separator if key name has more than one word. Always
+assume that all localized string keys for a class-based resource already
+have been assigned to the variable `$this.localizedData`.
+
+## Unit tests
 
 All tests should use the Pester framework and use Pester v5.0 syntax.
 
 Never test, mock or use `Should -Invoke` for `Write-Verbose` and `Write-Debug`
 regardless of other instructions.
 
+Parameter validation should not be tested in unit tests.
+
 Test code should never be added outside of the `Describe` block.
 
 Unit tests should be added for all public commands and private functions.
@@ -143,20 +175,21 @@ AfterAll {
 }
 ```
 
+## Integration tests
+
 Integration tests should be added for all public commands. Integration must
 never mock any command but run the command in a real environment. The integration
 tests should be placed in the folder tests/Integration/Commands and the
 integration tests should be named after the public command they are testing,
-but should have the suffix .Integration.Tests.ps1. The integration tests should be
-written to cover all possible scenarios and code paths, ensuring that both
+but should have the suffix .Integration.Tests.ps1. The integration tests should
+be written to cover all possible scenarios and code paths, ensuring that both
 edge cases and common use cases are tested. The integration tests should
 also be written to test the command in a real environment, using real
 resources and dependencies.
 
-The module being tested should not be imported in the integration tests.
-All integration tests should should use this code block prior to the `Describe`
-block which will set up the test environment and will make sure the correct
-module is available for testing:
+All integration tests must use the below code block prior to the first
+`Describe`-block. The following code will set up the integration test
+environment and it will make sure the module being tested is available
 
 ```powershell
 [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
@@ -183,4 +216,10 @@ BeforeDiscovery {
         throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.'
     }
 }
+
+BeforeAll {
+    $script:dscModuleName = 'SqlServerDsc'
+
+    Import-Module -Name $script:dscModuleName
+}
 ```