Improve documentation on functions.

YouTrackAutomation/Functions/Invoke-YTRestMethod.ps1

@@ -8,8 +8,8 @@ function Invoke-YTRestMethod
     .DESCRIPTION
     The `Invoke-YTRestMethod` function invokes a REST method in YouTrack using the provided session object. Pass in the
     name of the API endpoint to make the request to. By default, this function makes the HTTP request using the HTTP
-    `Get` method. Use the `Method` parameter to use a different HTTP method. Provide the body of the request using the
-    `Body` parameter.
+    `Get` method. Use the `Method` parameter to use a different HTTP method. Provide the body of the request as a
+    hashtable to the `Body` parameter.
 
     .EXAMPLE
     Invoke-YTRestMethod -Session $session -Name 'admin/projects'
@@ -36,10 +36,12 @@ function Invoke-YTRestMethod
         [Parameter(Mandatory)]
         [String] $Name,
 
+        # The type of request method, defaults to Get.
         [Microsoft.PowerShell.Commands.WebRequestMethod] $Method =
             [Microsoft.PowerShell.Commands.WebRequestMethod]::Get,
 
-        [Object] $Body
+        # The body of the request in the form of a hashtable.
+        [hashtable] $Body
     )
 
     Set-StrictMode -Version 'Latest'

YouTrackAutomation/Functions/New-YTIssue.ps1

@@ -6,9 +6,9 @@ function New-YTIssue
     Creates a new issue in YouTrack.
 
     .DESCRIPTION
-    The `New-YTIssue` function creates a new issue in YouTrack. Pass the short name of the project where the issue
-    should be created to the `Project` parameter, and the title of the issue to the `Summary` parameter. You can also
-    provide an optional description to the `Description` parameter.
+    The `New-YTIssue` function creates a new issue in YouTrack. Pass the project's short name, ID, or a project object
+    where the issue should get created to the Project parameter, and the title of the issue to the `Summary` parameter.
+    You can also provide an optional description to the `Description` parameter.
 
     .EXAMPLE
     New-YTIssue -Session $session -Project 'DEMO' -Summary 'New Issue'
@@ -44,13 +44,14 @@ function New-YTIssue
     Use-CallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
     $issueFields = @{
-        summary = $Summary
+        summary = $Summary;
         project = @{
-            id = Resolve-YTProjectId -Session $session -Project $Project
-        }
+            id = Resolve-YTProjectId -Session $session -Project $Project;
+        };
     }
 
-    if ($Description) {
+    if ($Description)
+    {
         $issueFields['description'] = $Description
     }
 

YouTrackAutomation/Functions/New-YTProject.ps1

@@ -66,11 +66,11 @@ function New-YTProject
 
     $fields = 'id,name,shortName'
     $body = @{
-        name = $Name
-        shortName = $ShortName
+        name = $Name;
+        shortName = $ShortName;
         leader = @{
-            id = $Leader
-        }
+            id = $Leader;
+        };
     }
 
     if ($Description)

YouTrackAutomation/Functions/New-YTSession.ps1

@@ -6,9 +6,9 @@ function New-YTSession
     Creates a new YouTrack session object.
 
     .DESCRIPTION
-    The `New-YTSession` function creates a new YouTrack session object that can be used to interact with the YouTrack
-    API. Provide the URL of the YouTrack instance and an API token to create a new session. This session contains the
-    URL, the API key, and the YouTrackSharp `BearerTokenConnection` object.
+    The New-YTSession function creates a session object required by most YouTrackAutomation functions. Pass the URL to
+    YouTrack to the Url parameter and your API token to the ApiToken parameter. The URL should just be the protocol and
+    hostname. The function returns an object that can be passed to all YouTrackAutomation functions' Session parameter.
 
     .EXAMPLE
     $session = New-YTSession -Url 'https://my-youtrack-instance.com' -ApiToken 'my-api-key'

YouTrackAutomation/Functions/Remove-YTProject.ps1

@@ -21,7 +21,7 @@ function Remove-YTProject
     #>
     [CmdletBinding(SupportsShouldProcess)]
     param(
-        # The Session object for a YouTrack session. Create a new Session using `New-YTSession`.
+        # The session object for a YouTrack session. Create a new Session using `New-YTSession`.
         [Parameter(Mandatory)]
         [Object] $Session,
 
@@ -34,9 +34,5 @@ function Remove-YTProject
     Use-CallerPreference -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
 
     $projectId = Resolve-YTProjectId -Session $Session -Project $Project
-
-    if ($PSCmdlet.ShouldProcess($projectId, 'Remove YouTrack Project'))
-    {
-        Invoke-YTRestMethod -Session $Session -Method Delete -Name "admin/projects/${ProjectId}"
-    }
+    Invoke-YTRestMethod -Session $Session -Method Delete -Name "admin/projects/${ProjectId}"
 }

YouTrackAutomation/Functions/Resolve-YTProject.ps1

@@ -10,23 +10,23 @@ function Resolve-YTProjectId
     associated with the project provided.
 
     .EXAMPLE
-    Resolve-YTProject.ps1 -Session $session -Project 'DEMO'
+    Resolve-YTProject -Session $session -Project 'DEMO'
 
     Demonstrates resolving the project id for the project with the `DEMO` short name.
 
     .EXAMPLE
-    Resolve-YTProject.ps1 -Session $session -Project '0-1'
+    Resolve-YTProject -Session $session -Project '0-1'
 
     Demonstrates resolving the project id for the project with the `0-1` id.
 
     .EXAMPLE
-    Resolve-YTProject.ps1 -Session $session -Project $project
+    Resolve-YTProject -Session $session -Project $project
 
     Demonstrates resolving the project id for the project with a project object.
     #>
     [CmdletBinding()]
     param(
-        # The session object for a YouTrack Session. Create a new Session using `New-YTSession`.
+        # The session object for a YouTrack session. Create a new Session using `New-YTSession`.
         [Object] $Session,
 
         # The project to resolve the id for. Can be a project object, a project id, or a project short name.
@@ -38,17 +38,18 @@ function Resolve-YTProjectId
         return $Project.id
     }
 
-    if ($Project -is [String] -and $Project -match '^\d+-\d+$')
+    if (-not $Project -is [String])
     {
-        return $Project
+        $msg = "Failed to resolve project ""${Project}"": expected an object with an `id` property, a string ID " +
+            '(e.g. ''0-0''), or a project short name.'
+        Write-Error $msg
+        return
     }
 
-    if ($Project -is [String])
+    if ($Project -match '^\d+-\d+$')
     {
-        return Get-YTProject -Session $Session -ShortName $Project | Select-Object -ExpandProperty 'id'
+        return $Project
     }
 
-    $msg = "Failed to resolve project ""${Project}"": expected an object with an `id` property, a string ID " +
-           '(e.g. ''0-0''), or a project short name.'
-    Write-Error $msg
+    return Get-YTProject -Session $Session -ShortName $Project | Select-Object -ExpandProperty 'id'
 }

YouTrackAutomation/YouTrackAutomation.psd1

@@ -36,7 +36,7 @@
     Copyright = '(c) WebMD Health Services.'
 
     # Description of the functionality provided by this module
-    Description = 'A PowerShell wrapper for the YouTrack REST API.'
+    Description = 'A PowerShell module for the YouTrack REST API.'
 
     # Minimum version of the Windows PowerShell engine required by this module
     PowerShellVersion = '5.1'