Escape commas of parameter accepted values

[mmims]

If the validation set of a parameter has a string value which contains a comma, platyPS incorrectly interprets it as a separate value. String values with commas should be properly escaped or the markdown format should use a different separation character.

Example available at https://github.com/mmims/PSConsoleTheme/blob/master/docs/Get-ConsoleTheme.md. See the 'Gruvbox dark, hard', 'Gruvbox dark, medium', 'Gruvbox dark, pale', 'Gruvbox dark, soft', 'Gruvbox light, hard', 'Gruvbox light, medium', and 'Gruvbox light, soft' values of the Name parameter.

Steps to reproduce

Create a parameter with a validation set containing a string with a character.

[ValidateSet('test', 'test, with comma')]
[string]$MyParam

Expected behavior

The powershell help file should produce something like this:

... SYNTAX MyCmdlet -MyParam {test | test, with comma} ...

Actual behavior

The powershell help file produces:

... SYNTAX MyCmdlet -MyParam {test | test | with comma} ...

Environment data

v0.9.0

[vors]

oh interesting, good catch!

[sdwheeler]

Needs testing in new version before release.

[sdwheeler]

PlatyPS doesn't include possible values in the SYNTAX blocks. Nor should it. The markdown should only contain the raw syntax. It produces the same syntax block you get from Get-Command. For example, look at the syntax information for the -Encoding parameter:

Get-Command Set-Content -Syntax

Set-Content [-Path] <string[]> [-Value] <Object[]> [-PassThru] [-Filter <string>] [-Include <string[]>] [-Exclude <string[]>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-NoNewline] [-Encoding <Encoding>] [-AsByteStream] [-Stream <string>] [<CommonParameters>]

Set-Content [-Value] <Object[]> -LiteralPath <string[]> [-PassThru] [-Filter <string>] [-Include <string[]>] [-Exclude <string[]>] [-Force] [-Credential <pscredential>] [-WhatIf] [-Confirm] [-NoNewline] [-Encoding <Encoding>] [-AsByteStream] [-Stream <string>] [<CommonParameters>]

In contrast, the syntax output from Get-Help includes the possible values:

get-help set-content

NAME
    Set-Content

SYNOPSIS
    Writes new content or replaces existing content in a file.


SYNTAX
    Set-Content [-Value] <System.Object[]> [-AsByteStream] [-Credential <System.Management.Automation.PSCredential>]
    [-Encoding {ASCII | BigEndianUnicode | BigEndianUTF32 | OEM | Unicode | UTF7 | UTF8 | UTF8BOM | UTF8NoBOM |
    UTF32}] [-Exclude <System.String[]>] [-Filter <System.String>] [-Force] [-Include <System.String[]>] -LiteralPath
    <System.String[]> [-NoNewline] [-PassThru] [-Stream <System.String>] [-Confirm] [-WhatIf] [<CommonParameters>]

    Set-Content [-Path] <System.String[]> [-Value] <System.Object[]> [-AsByteStream] [-Credential
    <System.Management.Automation.PSCredential>] [-Encoding {ASCII | BigEndianUnicode | BigEndianUTF32 | OEM | Unicode
    | UTF7 | UTF8 | UTF8BOM | UTF8NoBOM | UTF32}] [-Exclude <System.String[]>] [-Filter <System.String>] [-Force]
    [-Include <System.String[]>] [-NoNewline] [-PassThru] [-Stream <System.String>] [-Confirm] [-WhatIf]
    [<CommonParameters>]

This is by design.