Show comment based help for Invoke-ShlinkRestMethod in docs

Author: codaamok

.vscode/tasks.json

@@ -23,7 +23,7 @@
             "label": "Build (with docs)",
             "type": "process",
             "command": "pwsh",
-            "args": ["-noprofile","-command","Invoke-Build","-File","./invoke.build.ps1","-Author","'codaamok'","-ModuleName","'PSShlink'","-UpdateDocs","$true","$true"],
+            "args": ["-noprofile","-command","Invoke-Build","-File","./invoke.build.ps1","-Author","'codaamok'","-ModuleName","'PSShlink'","-UpdateDocs","$true"],
             "group": {
                 "kind": "build",
                 "isDefault": true

CHANGELOG.md

@@ -5,6 +5,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Fixed
+- Show comment based help correctly for `Invoke-ShlinkRestMethod`, mostly for PlatyPS and in-repository help markdown files
 
 ## [0.12.0] - 2023-03-05
 ### Added

docs/Invoke-ShlinkRestMethod.md

@@ -8,7 +8,7 @@ schema: 2.0.0
 # Invoke-ShlinkRestMethod
 
 ## SYNOPSIS
-{{ Fill in the Synopsis }}
+Query a Shlink server's REST API
 
 ## SYNTAX
 
@@ -19,116 +19,162 @@ Invoke-ShlinkRestMethod [-Endpoint] <String> [[-Path] <String>] [[-Query] <HttpU
 ```
 
 ## DESCRIPTION
-{{ Fill in the Description }}
+This function provides flexibility to query a Shlink's server how you want to. 
+
+Specify all the parameters, endpoint, and path details you need.
+
+All data from all pages are returned.
+
+See Shlink's REST API documentation: https://shlink.io/documentation/api-docs/ and https://api-spec.shlink.io/
 
 ## EXAMPLES
 
-### Example 1
-```powershell
-PS C:\> {{ Add example code here }}
+### EXAMPLE 1
+```
+Invoke-ShlinkRestMethod -Endpoint "short-urls" -PropertyTree "shortUrls", "Data" -Query [System.Web.HttpUtility]::ParseQueryString("searchTerm", "abc")
+```
+
+Gets all short codes from Shlink matching the search term "abc".
+
+Note (it's not obvious), you can add more query params to an instance of HttpUtility like you can any dictionary by using the .Add() method on the object.
+
+### EXAMPLE 2
+```
+Invoke-ShlinkRestMethod -Endpoint "short-urls" -Path "abc" -METHOD "DELETE"
 ```
 
-{{ Add example description here }}
+Deletes the shortcode "abc" from Shlink.
+
+### EXAMPLE 3
+```
+Invoke-ShlinkRestMethod -Endpoint "tags" -Path "stats"
+```
+
+Gets all tags with statistics.
 
 ## PARAMETERS
 
-### -ApiVersion
-{{ Fill ApiVersion Description }}
+### -Endpoint
+The endpoint to use in the request.
+This is before the -Path.
+See the examples for example usage.
 
 ```yaml
-Type: Int32
+Type: String
 Parameter Sets: (All)
 Aliases:
-Accepted values: 1, 2, 3
 
-Required: False
-Position: 3
+Required: True
+Position: 1
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Endpoint
-{{ Fill Endpoint Description }}
+### -Path
+The path to use in the request.
+This is after the -Endpoint.
+See the examples for example usage.
 
 ```yaml
 Type: String
 Parameter Sets: (All)
 Aliases:
 
-Required: True
-Position: 0
+Required: False
+Position: 2
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Method
-{{ Fill Method Description }}
+### -Query
+The query to use in the request.
+Must be an instance of System.Web.HttpUtility.
+See the examples for example usage.
+
+Note (it's not obvious), you can add more query params to an instance of HttpUtility like you can any dictionary by using the .Add() method on the object.
 
 ```yaml
-Type: WebRequestMethod
+Type: HttpUtility
 Parameter Sets: (All)
 Aliases:
-Accepted values: Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
 
 Required: False
-Position: 4
+Position: 3
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Path
-{{ Fill Path Description }}
+### -ApiVersion
+The API version of Shlink to use in the request.
 
 ```yaml
-Type: String
+Type: Int32
 Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 1
-Default value: None
+Position: 4
+Default value: 3
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PropertyTree
-{{ Fill PropertyTree Description }}
+### -Method
+The HTTP method to use in the request.
 
 ```yaml
-Type: String[]
+Type: WebRequestMethod
 Parameter Sets: (All)
 Aliases:
+Accepted values: Default, Get, Head, Post, Put, Delete, Trace, Options, Merge, Patch
 
 Required: False
 Position: 5
-Default value: None
+Default value: GET
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Query
-{{ Fill Query Description }}
+### -PropertyTree
+Data returned by Shlink's rest API is usually embedded within one or two properties.
+
+Here you can specify the embedded properties as a string array in the order you need to select them to access the data.
+
+For example, the "short-urls" endpoint includes the data within the "shortUrls.data" properties.
+Therefore, for this parameter you specify a string array of @("shortUrls", "data").
+
+In other words, using this function for the short-urls endpoint results in the below object if there are two pages worth of data returned:
+
+    Invoke-ShlinkRestMethod -Endpoint 'short-urls'
+
+    shortUrls
+    ---------
+    @{data=System.Object\[\]; pagination=}
+    @{data=System.Object\[\]; pagination=}
 
 ```yaml
-Type: HttpUtility
+Type: String[]
 Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 2
+Position: 6
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ShlinkApiKey
-{{ Fill ShlinkApiKey Description }}
+### -ShlinkServer
+The URL of your Shlink server (including schema).
+For example "https://example.com".
+It is not required to use this parameter for every use of this function.
+When it is used once for any of the functions in the PSShlink module, its value is retained throughout the life of the PowerShell session and its value is only accessible within the module's scope.
 
 ```yaml
-Type: SecureString
+Type: String
 Parameter Sets: (All)
 Aliases:
 
@@ -139,16 +185,18 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ShlinkServer
-{{ Fill ShlinkServer Description }}
+### -ShlinkApiKey
+A SecureString object of your Shlink server's API key.
+It is not required to use this parameter for every use of this function.
+When it is used once for any of the functions in the PSShlink module, its value is retained throughout the life of the PowerShell session and its value is only accessible within the module's scope.
 
 ```yaml
-Type: String
+Type: SecureString
 Parameter Sets: (All)
 Aliases:
 
 Required: False
-Position: 6
+Position: 8
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
@@ -159,10 +207,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## INPUTS
 
-### None
+### This function does not accept pipeline input.
 ## OUTPUTS
 
-### System.Object
+### System.Management.Automation.PSObject
 ## NOTES
 
 ## RELATED LINKS

src/Public/Invoke-ShlinkRestMethod.ps1

@@ -1,5 +1,4 @@
 function Invoke-ShlinkRestMethod {
-    # TODO this function needs tests
     <#
     .SYNOPSIS
         Query a Shlink server's REST API
@@ -91,6 +90,8 @@ function Invoke-ShlinkRestMethod {
         [Parameter()]
         [SecureString]$ShlinkApiKey
     )
+    
+    # TODO this function needs tests
 
     try {
         GetShlinkConnection -Server $ShlinkServer -ApiKey $ShlinkApiKey