Enhance Help Documentation Validation for Cmdlets (#548)

* build: added mechanisms to check for examples and parameters in docs

* docs: updated the contrtibution part

* docs: updated cmdlet documentation with parameters

* docs: updated cmdlet documentation with examples

* feat: set to version 7.15.1

Author: SebastianSchuetze

.docs/Add-VSTeamAccessControlEntry.md

@@ -14,6 +14,48 @@
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+Add-VSTeamAccessControlEntry -SecurityNamespaceId "2bf24a2b-70ba-43d3-ad97-3d9e1f75622f" -Token "MySecurityToken" -AllowMask 15 -DenyMask 2 -ProjectName "MyProject"
+```
+
+This command adds an Access Control Entry (ACE) for the provided token in the project named "MyProject" using the specified security namespace identifier. The ACE has an allow mask of 15 and a deny mask of 2.
+
+### Example 2
+
+```powershell
+Add-VSTeamAccessControlEntry -SecurityNamespace "vsteam_lib.SecurityNamespace" -Token "MySecurityToken" -AllowMask 7 -DenyMask 0 -OverwriteMask -ProjectName "MyProject"
+```
+
+This example adds an ACE using a `vsteam_lib.SecurityNamespace` object instead of a security namespace identifier. The allow mask is set to 7, and the deny mask is set to 0. The `-OverwriteMask` switch is used, which means the mask values will be overwritten rather than merged.
+
+### Example 3
+
+```powershell
+$aceParams = @{
+    SecurityNamespaceId = "2bf24a2b-70ba-43d3-ad97-3d9e1f75622f";
+    Token = "MySecurityToken";
+    AllowMask = 31;
+    DenyMask = 8;
+    ProjectName = "MyProject";
+}
+Add-VSTeamAccessControlEntry @aceParams
+```
+
+This example uses a hashtable to define the parameters for the `Add-VSTeamAccessControlEntry` cmdlet. The ACE is added with an allow mask of 31 and a deny mask of 8 for the provided token in the project "MyProject".
+
+### Example 4
+
+```powershell
+$namespace = Get-VSTeamSecurityNamespace -Name "VersionControlItems"
+Add-VSTeamAccessControlEntry -SecurityNamespace $namespace -Token "MyToken" -AllowMask 3 -DenyMask 1 -ProjectName "MyProject"
+```
+
+This example first retrieves the security namespace object for "VersionControlItems" and then uses this object to add an ACE. The ACE is added with an allow mask of 3 and a deny mask of 1 for the token "MyToken" in the project "MyProject".
+
+Remember, managing permissions and access control entries in a DevOps environment is a crucial task, ensuring that users and services have the appropriate permissions for their roles and responsibilities. Always be careful when modifying permissions to avoid unintentionally giving or restricting access to critical resources.
+
 ## PARAMETERS
 
 ### SecurityNamespace
@@ -123,6 +165,15 @@ Parameter Sets: ByNamespaceId
 Required: True
 ```
 
+### Descriptor
+
+Descriptor of the token to be added.
+
+```yaml
+Type: String
+Required: True
+```
+
 ### Token
 
 The security Token
@@ -151,7 +202,7 @@ Required: True
 ```
 ### OverwriteMask
 
-Switch to overwrite the mask values rather than merge them. 
+Switch to overwrite the mask values rather than merge them.
 
 ```yaml
 Type: Switch

.docs/Add-VSTeamAzureRMServiceEndpoint.md

@@ -14,6 +14,48 @@ The cmdlet adds a new connection between TFS/AzD and Azure using the Azure Resou
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+Add-VSTeamAzureRMServiceEndpoint -SubscriptionName "MyAzureSubscription" -SubscriptionId "1234abcd-5678-efgh-9012-ijklmn345678" -SubscriptionTenantId "abcd1234-efgh-5678-ijkl-9012mn345678" -ServicePrincipalId "efgh1234-5678-abcd-9012-ijklmn345678" -ServicePrincipalKey "my-service-principal-key" -EndpointName "MyAzureEndpoint" -ProjectName "MyProject"
+```
+
+This command adds a new Azure Resource Manager service endpoint in the project named "MyProject" using the provided Azure subscription name, subscription ID, tenant ID, service principal ID, and service principal key. The service endpoint will be named "MyAzureEndpoint".
+
+### Example 2
+
+```powershell
+$params = @{
+    SubscriptionName = "MyAzureSubscription";
+    SubscriptionId = "1234abcd-5678-efgh-9012-ijklmn345678";
+    SubscriptionTenantId = "abcd1234-efgh-5678-ijkl-9012mn345678";
+    ServicePrincipalId = "efgh1234-5678-abcd-9012-ijklmn345678";
+    ServicePrincipalKey = "my-service-principal-key";
+    EndpointName = "MyAzureEndpoint";
+    ProjectName = "MyProject";
+}
+Add-VSTeamAzureRMServiceEndpoint @params
+```
+
+This example does the same as the previous one but uses a hashtable to define the parameters for the `Add-VSTeamAzureRMServiceEndpoint` cmdlet.
+
+### Example 3
+
+```powershell
+$endpoint = @{
+    SubscriptionName = "MyAzureSubscription";
+    SubscriptionId = "1234abcd-5678-efgh-9012-ijklmn345678";
+    SubscriptionTenantId = "abcd1234-efgh-5678-ijkl-9012mn345678";
+    ServicePrincipalId = "efgh1234-5678-abcd-9012-ijklmn345678";
+    ServicePrincipalKey = "my-service-principal-key";
+}
+Add-VSTeamAzureRMServiceEndpoint @endpoint -EndpointName "MyAzureEndpoint" -ProjectName "MyProject"
+```
+
+This example demonstrates how you can separate the Azure-related parameters and the Azure DevOps-related parameters. The Azure parameters are stored in the `$endpoint` hashtable, and the Azure DevOps parameters are provided directly to the cmdlet.
+
+Remember that when working with Azure, Service Principals are a way to give applications permissions in Azure Active Directory. This allows those applications to manage resources in Azure. The Service Principal ID and Key are used to authenticate and authorize the application. Always handle the Service Principal Key with care as it is a sensitive piece of information.
+
 ## PARAMETERS
 
 ### SubscriptionName
@@ -82,6 +124,14 @@ Type: String
 Position: 4
 ```
 
+### Description
+
+Description of the service endpoint.
+
+```yaml
+Type: String
+```
+
 <!-- #include "./params/projectName.md" -->
 
 ## INPUTS

.docs/Add-VSTeamBanner.md

@@ -17,7 +17,7 @@
 ### Example 1
 
 ```powershell
-Add-VSTeamBanner -Level info -Message 'Test Message' -ExpirationDate '2024-01-01T04:00' -BannerId '9547ed55-66e1-403d-95aa-9e628726861c'
+Add-VSTeamBanner -Level info -Message 'Test Message' -ExpirationDate '2024-01-01T04:00' -Id '9547ed55-66e1-403d-95aa-9e628726861c'
 ```
 
 ## PARAMETERS
@@ -53,7 +53,7 @@ Type: String
 Required: True
 ```
 
-### BannerId
+### Id
 
 The unique identifier for the banner.
 

.docs/Add-VSTeamBuild.md

@@ -98,6 +98,10 @@ Which source branch to use for this build. Overrides default branch in build def
 Type: String
 ```
 
+### TemplateParameters
+
+ Allows the user to pass in dynamic values to the build pipeline when queuing a new build, potentially influencing how the build runs based on the values of these parameters.
+
 ### BuildParameters
 
 A hashtable with build parameters.

.docs/Add-VSTeamBuildPermission.md

@@ -47,6 +47,10 @@ Allows the user 'test@testuser.com' to the build with ID 5 to destry builds and
 
 ## PARAMETERS
 
+### ProjectID
+
+ID of the project.
+
 ### BuildID
 
 The build ID of the build pipeline to permit the identity object to.

.docs/Add-VSTeamBuildTag.md

@@ -14,6 +14,58 @@ Adds a tag to a build.
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+Add-VSTeamBuildTag -Id 12345 -Tags "QA_Passed" -ProjectName "MyProject"
+```
+
+This command adds the tag "QA_Passed" to the build with ID 12345 in the project named "MyProject".
+
+### Example 2
+
+```powershell
+$builds = Get-VSTeamBuild -ProjectName "MyProject" -Result Succeeded
+$builds | Add-VSTeamBuildTag -Tags "ProductionReady"
+```
+
+This example first retrieves all builds in the "MyProject" project that have succeeded. It then adds the tag "ProductionReady" to each of these builds.
+
+### Example 3
+
+```powershell
+Add-VSTeamBuildTag -Id 67890,12345 -Tags "Reviewed,ReadyForDeploy" -ProjectName "MyProject"
+```
+
+This command adds the tags "Reviewed" and "ReadyForDeploy" to the builds with IDs 67890 and 12345 in the project named "MyProject".
+
+### Example 4
+
+```powershell
+$tags = "Version2.0", "ReleaseCandidate"
+Add-VSTeamBuildTag -Id 98765 -Tags $tags -ProjectName "MyProject"
+```
+
+This example adds the tags "Version2.0" and "ReleaseCandidate" to the build with ID 98765 in the project named "MyProject".
+
+### Example 5
+
+```powershell
+Add-VSTeamBuildTag -Id 11223 -Tags "RegressionTested" -ProjectName "MyProject" -Confirm
+```
+
+This command adds the tag "RegressionTested" to the build with ID 11223 in the project named "MyProject". It will prompt for confirmation before adding the tag.
+
+### Example 6
+
+```powershell
+$buildId = 44556
+$myTags = "UI_Passed", "Backend_Tested"
+Add-VSTeamBuildTag -Id $buildId -Tags $myTags -ProjectName "MyProject" -Force
+```
+
+This example adds the tags "UI_Passed" and "Backend_Tested" to the build with ID 44556 in the project named "MyProject". The `-Force` parameter ensures the tags are added without any confirmation prompt.
+
 ## PARAMETERS
 
 <!-- #include "./params/buildIds.md" -->

.docs/Add-VSTeamExtension.md

@@ -14,6 +14,56 @@
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+Add-VSTeamExtension -PublisherId "MyPublisher" -ExtensionId "MyExtension"
+```
+
+This command installs the specified extension "MyExtension" from the publisher "MyPublisher" into the account/project collection.
+
+### Example 2
+
+```powershell
+Add-VSTeamExtension -PublisherId "AnotherPublisher" -ExtensionId "AnotherExtension" -Version "1.2.3"
+```
+
+This command installs version "1.2.3" of the extension "AnotherExtension" from the publisher "AnotherPublisher" into the account/project collection.
+
+### Example 3
+
+```powershell
+$myExtensionDetails = @{
+    PublisherId = "SamplePublisher";
+    ExtensionId = "SampleExtension";
+    Version = "2.0.0";
+}
+
+Add-VSTeamExtension @myExtensionDetails
+```
+
+This example uses a hashtable to specify the details of the extension and installs version "2.0.0" of the extension "SampleExtension" from the publisher "SamplePublisher" into the account/project collection.
+
+### Example 4
+
+```powershell
+$extensions = Import-Csv -Path "C:\path\to\extensions.csv"
+
+foreach ($ext in $extensions) {
+    Add-VSTeamExtension -PublisherId $ext.PublisherId -ExtensionId $ext.ExtensionId -Version $ext.Version
+}
+```
+
+This example reads a CSV file containing a list of extensions with their PublisherId, ExtensionId, and Version, and installs each extension into the account/project collection.
+
+### Example 5
+
+```powershell
+Add-VSTeamExtension -PublisherId "DevOpsTools" -ExtensionId "CI_CD_Tool"
+```
+
+This command installs the specified extension "CI_CD_Tool" from the publisher "DevOpsTools" into the account/project collection. If there are multiple versions available, the latest version will be installed by default.
+
 ## PARAMETERS
 
 ### PublisherId

.docs/Add-VSTeamGitRepositoryPermission.md

@@ -14,6 +14,52 @@
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+$descriptorUser = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMA"
+$descriptorGroup = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMQ"
+Add-VSTeamGitRepositoryPermission -RepositoryId "1a2b3c4d" -RepositoryName "MyRepo" -BranchName "main" -Descriptor $descriptorUser -User $descriptorUser -Group $descriptorGroup -Allow "Read,Contribute" -Deny "Delete" -ProjectName "WebAppProject"
+```
+
+This command adds read and contribute permissions to the "main" branch of the "MyRepo" repository for the specified user and group while denying the delete permission. The user and group are specified using their respective descriptors.
+
+### Example 2
+
+```powershell
+$descriptorUser = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMA"
+Add-VSTeamGitRepositoryPermission -RepositoryId "2b3c4d5e" -RepositoryName "AnotherRepo" -BranchName "dev" -Descriptor $descriptorUser -User $descriptorUser -Allow "Read" -ProjectName "BackendServices"
+```
+
+Here, read permission is granted to the "dev" branch of the "AnotherRepo" repository for the specified user using the user descriptor.
+
+### Example 3
+
+```powershell
+$descriptorGroup = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMQ"
+Add-VSTeamGitRepositoryPermission -RepositoryId "3c4d5e6f" -RepositoryName "ThirdRepo" -BranchName "feature" -Descriptor $descriptorGroup -Group $descriptorGroup -Allow "Read,Contribute,Manage" -ProjectName "DataAnalytics"
+```
+
+In this example, read, contribute, and manage permissions are granted to the "feature" branch of the "ThirdRepo" repository for the specified group using the group descriptor.
+
+### Example 4
+
+```powershell
+$descriptorUser = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMA"
+Add-VSTeamGitRepositoryPermission -RepositoryId "4d5e6f7g" -RepositoryName "FourthRepo" -BranchName "hotfix" -Descriptor $descriptorUser -User $descriptorUser -Allow "Read" -Deny "Contribute,Delete" -ProjectName "MobileApp"
+```
+
+This command grants read permission and denies contribute and delete permissions to the "hotfix" branch of the "FourthRepo" repository for the specified user using the user descriptor.
+
+### Example 5
+
+```powershell
+$descriptorGroup = "vssgp.Uy0xLTktMTU1MTM3NDI0NS0xMzM4Mzc4Njg5LTE5MzM0NTM5NjYtMzQ3NzU4NjI4OS0yNTA2ODc2NTA5LTAuMQ"
+Add-VSTeamGitRepositoryPermission -RepositoryId "5e6f7g8h" -RepositoryName "FifthRepo" -BranchName "release" -Descriptor $descriptorGroup -Group $descriptorGroup -Allow "Read,Contribute" -ProjectName "FrontendUI"
+```
+
+This example grants read and contribute permissions to the "release" branch of the "FifthRepo" repository for the specified group using the group descriptor.
+
 ## PARAMETERS
 
 ### RepositoryId

.docs/Add-VSTeamKubernetesEndpoint.md

@@ -16,6 +16,51 @@ This is only used when using the Kubernetes tasks.
 
 ## EXAMPLES
 
+### Example 1
+
+```powershell
+$kubeconfig = Get-Content -Path "C:\path\to\kubeconfig.json" -Raw
+Add-VSTeamKubernetesEndpoint -Kubeconfig $kubeconfig -KubernetesUrl "https://k8s-cluster.example.com:6443" -EndpointName "MyK8sCluster" -ClientCertificateData "CERTIFICATE_DATA" -ClientKeyData "KEY_DATA" -AcceptUntrustedCerts -GeneratePfx -ProjectName "WebAppProject"
+```
+
+This command creates a new connection to a Kubernetes cluster using the provided kubeconfig file and details. The connection is named "MyK8sCluster" and is associated with the "WebAppProject". It accepts untrusted certificates and generates a pfx file.
+
+### Example 2
+
+```powershell
+$kubeconfig = Get-Content -Path "C:\path\to\another\kubeconfig.json" -Raw
+Add-VSTeamKubernetesEndpoint -Kubeconfig $kubeconfig -KubernetesUrl "https://another-k8s-cluster.example.org:6443" -EndpointName "AnotherK8sCluster" -ClientCertificateData "ANOTHER_CERTIFICATE_DATA" -ClientKeyData "ANOTHER_KEY_DATA" -ProjectName "BackendServices"
+```
+
+Here, a new Kubernetes connection named "AnotherK8sCluster" is created for the "BackendServices" project using the provided kubeconfig file and details.
+
+### Example 3
+
+```powershell
+$kubeconfig = Get-Content -Path "C:\path\to\third\kubeconfig.json" -Raw
+Add-VSTeamKubernetesEndpoint -Kubeconfig $kubeconfig -KubernetesUrl "https://third-k8s-cluster.example.net:6443" -EndpointName "ThirdK8sCluster" -ClientCertificateData "THIRD_CERTIFICATE_DATA" -ClientKeyData "THIRD_KEY_DATA" -GeneratePfx -ProjectName "DataAnalytics"
+```
+
+In this example, a connection to a third Kubernetes cluster is created with the name "ThirdK8sCluster" for the "DataAnalytics" project. It uses the provided kubeconfig file and details and generates a pfx file.
+
+### Example 4
+
+```powershell
+$kubeconfig = Get-Content -Path "C:\path\to\fourth\kubeconfig.yaml" -Raw
+Add-VSTeamKubernetesEndpoint -Kubeconfig $kubeconfig -KubernetesUrl "https://fourth-k8s-cluster.example.io:6443" -EndpointName "FourthK8sCluster" -ClientCertificateData "FOURTH_CERTIFICATE_DATA" -ClientKeyData "FOURTH_KEY_DATA" -AcceptUntrustedCerts -ProjectName "MobileApp"
+```
+
+This command creates a new Kubernetes connection named "FourthK8sCluster" for the "MobileApp" project. It uses the provided kubeconfig file, details, and accepts untrusted certificates.
+
+### Example 5
+
+```powershell
+$kubeconfig = Get-Content -Path "C:\path\to\fifth\kubeconfig.yaml" -Raw
+Add-VSTeamKubernetesEndpoint -Kubeconfig $kubeconfig -KubernetesUrl "https://fifth-k8s-cluster.example.co:6443" -EndpointName "FifthK8sCluster" -ClientCertificateData "FIFTH_CERTIFICATE_DATA" -ClientKeyData "FIFTH_KEY_DATA" -ProjectName "FrontendUI"
+```
+
+This example demonstrates the creation of a new Kubernetes connection named "FifthK8sCluster" for the "FrontendUI" project using the provided kubeconfig file and details.
+
 ## PARAMETERS
 
 ### Kubeconfig