Merge pull request #2 from robinmalik/development

Add comment based help to all functions

CHANGELOG.md

@@ -1,3 +1,11 @@
+## [0.0.3] - 2023-10-22
+
+* 📚 [Added] Documented all functions with comment-based help.
+
+## [0.0.2] - 2023-10-21
+
+* ✨ [New] Add a GitHub workflow for publishing to the PowerShell Gallery.
+
 ## [0.0.1] - 2023-10-21
 
 * 🎉 Initial release.

Source/PSSemaphore.psd1

@@ -12,7 +12,7 @@
     RootModule        = 'PSSemaphore.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '0.0.2'
+    ModuleVersion     = '0.0.3'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()

Source/Public/Connect-Semaphore.ps1

@@ -1,5 +1,27 @@
 function Connect-Semaphore
 {
+	<#
+		.SYNOPSIS
+			Connects to Semaphore.
+
+		.DESCRIPTION
+			This function connects to Semaphore.
+
+		.PARAMETER Url
+			The URL of the Semaphore instance to connect to.
+
+		.PARAMETER Credential
+			The credentials to use to connect to Semaphore.
+
+		.EXAMPLE
+			Connect-Semaphore -Url https://semaphore.example.com -Credential (Get-Credential)
+
+			Connects to the Semaphore instance at https://semaphore.example.com using the credentials provided.
+
+		.NOTES
+			N/A
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Disable-SemaphoreUserToken.ps1

@@ -1,5 +1,24 @@
 function Disable-SemaphoreUserToken
 {
+	<#
+		.SYNOPSIS
+			Disables a Semaphore user token for the currently authenticated user.
+
+		.DESCRIPTION
+			This function disables a Semaphore user token for the currently authenticated user.
+
+		.PARAMETER TokenId
+			The ID of the token to disable.
+
+		.EXAMPLE
+			Disable-SemaphoreUserToken -TokenId 1
+
+			Disables the token with ID 1.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding(SupportsShouldProcess)]
 	[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'Does not alter system state.')]
 	param (

Source/Public/Get-SemaphoreProject.ps1

@@ -1,5 +1,29 @@
 function Get-SemaphoreProject
 {
+	<#
+		.SYNOPSIS
+			Returns projects for the current Semaphore instance.
+
+		.DESCRIPTION
+			This function returns projects for the current Semaphore instance.
+
+		.PARAMETER Name
+			(Optional) The name of the project to retrieve. If specified, only the project with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProject
+
+			Retrieves information about all projects.
+
+		.EXAMPLE
+			Get-SemaphoreProject -Name "MyProject"
+
+			Retrieves information about the project with the name "MyProject."
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $false)]

Source/Public/Get-SemaphoreProjectEnvironment.ps1

@@ -1,5 +1,32 @@
 function Get-SemaphoreProjectEnvironment
 {
+	<#
+		.SYNOPSIS
+			Returns project environments for the given project.
+
+		.DESCRIPTION
+			This function retrieves information about environments associated with a project.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve environments.
+
+		.PARAMETER Name
+			(Optional) The name of the environment to retrieve. If specified, only the environment with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectEnvironment -ProjectId 2
+
+			Retrieves all environments under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectEnvironment -ProjectId 5 -Name "Production"
+
+			Retrieves the "Production" environment for the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreProjectInventory.ps1

@@ -1,5 +1,32 @@
 function Get-SemaphoreProjectInventory
 {
+	<#
+		.SYNOPSIS
+			Returns inventories for the given project.
+
+		.DESCRIPTION
+			This function retrieves information about inventories associated with a project.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve environments.
+
+		.PARAMETER Name
+			(Optional) The name of the inventory to retrieve. If specified, only the inventory with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectInventory -ProjectId 2
+
+			Retrieves all inventories under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectInventory -ProjectId 5 -Name "AllHosts"
+
+			Retrieves the "AllHosts" inventory for the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreProjectKey.ps1

@@ -1,5 +1,32 @@
 function Get-SemaphoreProjectKey
 {
+	<#
+		.SYNOPSIS
+			Returns keys for the given project.
+
+		.DESCRIPTION
+			This function retrieves information about keys associated with a project.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve keys.
+
+		.PARAMETER Name
+			(Optional) The name of the key to retrieve. If specified, only the key with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectKey -ProjectId 2
+
+			Retrieves all keys under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectKey -ProjectId 5 -Name "MyAccount"
+
+			Retrieves the "MyAccount" key for the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreProjectRepository.ps1

@@ -1,5 +1,32 @@
 function Get-SemaphoreProjectRepository
 {
+	<#
+		.SYNOPSIS
+			Returns repositories for the given project.
+
+		.DESCRIPTION
+			This function retrieves information about repositories associated with a project.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve repositories.
+
+		.PARAMETER Name
+			(Optional) The name of the repository to retrieve. If specified, only the repository with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectRepository -ProjectId 2
+
+			Retrieves all repositories under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectRepository -ProjectId 5 -Name "AnsiblePlaybooks"
+
+			Retrieves the "AnsiblePlaybooks" repository for the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreProjectTask.ps1

@@ -1,5 +1,35 @@
 function Get-SemaphoreProjectTask
 {
+	<#
+		.SYNOPSIS
+			Returns tasks for the given project and optionally, template.
+
+		.DESCRIPTION
+			This function retrieves information about tasks associated with a project and optionally, template.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve tasks.
+
+		.PARAMETER Id
+			(Optional) The ID of the task to retrieve. If specified, only the task with a matching ID will be returned.
+
+		.PARAMETER TemplateId
+			(Optional) The ID of the template to retrieve tasks for. If specified, only tasks associated with the template with a matching ID will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectTask -ProjectId 2
+
+			Retrieves all tasks under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectTask -ProjectId 5 -TemplateId 2
+
+			Retrieves all tasks for the template with ID 2 under the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreProjectTemplate.ps1

@@ -1,5 +1,35 @@
 function Get-SemaphoreProjectTemplate
 {
+	<#
+		.SYNOPSIS
+			Returns templates for the given project.
+
+		.DESCRIPTION
+			This function retrieves information about templates associated with a project.
+
+		.PARAMETER ProjectId
+			The ID of the project for which you want to retrieve templates.
+
+		.PARAMETER Id
+			(Optional) The ID of the template to retrieve. If specified, only the template with a matching ID will be returned.
+
+		.PARAMETER Name
+			(Optional) The name of the template to retrieve. If specified, only the template with a matching name will be returned.
+
+		.EXAMPLE
+			Get-SemaphoreProjectTemplate -ProjectId 2
+
+			Retrieves all templates under the project with ID 2.
+
+		.EXAMPLE
+			Get-SemaphoreProjectTemplate -ProjectId 5 -TemplateId 2
+
+			Retrieves all templates for the template with ID 2 under the project with ID 5.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding(DefaultParameterSetName = 'Default')]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/Get-SemaphoreUserToken.ps1

@@ -1,6 +1,22 @@
 function Get-SemaphoreUserToken
 {
-	[CmdletBinding(SupportsShouldProcess)]
+	<#
+		.SYNOPSIS
+			Returns user tokens for the given project.
+
+		.DESCRIPTION
+			This function retrieves user tokens for the logged in user.
+
+		.EXAMPLE
+			Get-SemaphoreUserToken
+
+			Retrieves all user tokens for the logged in user.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
+	[CmdletBinding()]
 	param (
 	)
 

Source/Public/New-SemaphoreProject.ps1

@@ -1,5 +1,38 @@
 function New-SemaphoreProject
 {
+	<#
+		.SYNOPSIS
+			Creates a new project.
+
+		.DESCRIPTION
+			Creates a new project.
+
+		.PARAMETER Name
+			The name of the project to create.
+
+		.PARAMETER Alert
+			(Optional) Whether to send alerts for this project.
+
+		.PARAMETER TelegramChatId
+			(Optional) The Telegram chat ID to send alerts to.
+
+		.PARAMETER MaxParallelTasks
+			(Optional) The maximum number of parallel tasks to run.
+
+		.EXAMPLE
+			New-SemaphoreProject -Name "My Project"
+
+			Creates a new project with the name "My Project".
+
+		.EXAMPLE
+			New-SemaphoreProject -Name "My Project" -Alert -TelegramChatId "123456789" -MaxParallelTasks 5
+
+			Creates a new project with the name "My Project", with alerts enabled, sending alerts to the Telegram chat with ID "123456789", and with a maximum of 5 parallel tasks.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+		#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]

Source/Public/New-SemaphoreProjectEnvironment.ps1

@@ -1,5 +1,27 @@
 function New-SemaphoreProjectEnvironment
 {
+	<#
+		.SYNOPSIS
+			Creates a new environment for the given project.
+
+		.DESCRIPTION
+			This function creates a new environment for the given project.
+
+		.PARAMETER ProjectId
+			The ID of the project to create the environment for.
+
+		.PARAMETER Name
+			The name of the environment to create.
+
+		.EXAMPLE
+			New-SemaphoreProjectEnvironment -ProjectId 2 -Name "Production"
+
+			Creates a new environment with the name "Production" for the project with ID 2.
+
+		.NOTES
+			To use this function, make sure you have already connected using the Connect-Semaphore function.
+	#>
+
 	[CmdletBinding()]
 	param (
 		[Parameter(Mandatory = $true)]