Syntax sections notation intermittent issue

[BernieWhite]

Ok possibly I've gone mad here, or there is a default behaviour of the PowerShell engine that is unexpected. But closely inspecting the parameters of functions in platyPS I'm not convinced that mandatory and positional/named parameters are correctly represented. The behaviour seems inconsistent.

I would expect -Path to use the form -Path <String[]> in Update-MarkdownHelp because it is mandatory and not flagged as positional. Likewise I would expect Encoding and LogPath to not use [] around the parameter name indicating positional form. But then -Session is correct.

Steps to reproduce

Update module docs .i.e. Update-MarkdownHelp .\docs\.

Expected behavior

Update-MarkdownHelp -Path <String[]> [-Encoding <Encoding>] [-LogPath <String>] [-LogAppend] [-AlphabeticParamsOrder] [-UseFullTypeName] [-Session <PSSession>] [<CommonParameters>]

Actual behavior

Update-MarkdownHelp [-Path] <String[]> [[-Encoding] <Encoding>] [[-LogPath] <String>] [-LogAppend]
 [-AlphabeticParamsOrder] [-UseFullTypeName] [-Session <PSSession>] [<CommonParameters>]

Environment data

v0.9.0, master

[BernieWhite]

Hmm looks like it is actually -Session that is incorrect. A dump from Get-Help without a MAML using the engine I get this:

name	position
AlphabeticParamsOrder	Named
Encoding	1
LogAppend	Named
LogPath	2
Path	0
Session	3
UseFullTypeName	Named

[vors]

Can you help me understand it better with some minimal repro? Is it help engine problem or platyPS?

[sdwheeler]

Repro steps:

1. Run Get-Command -Syntax on Update-MarkdownHelp
2. Run New-MarkdownHelp -Command Update-MarkdownHelp
3. Compare results

Example:

PS C:\Git\PS-Other\platyPS> gcm Update-MarkdownHelp -Syntax

Update-MarkdownHelp [-Path] <string[]> [[-Encoding] <Encoding>] [[-LogPath] <string>] [[-Session] <PSSession>] [-LogAppend] [-AlphabeticParamsOrder] [-UseFullTypeName] [-UpdateInputOutput] [-Force] [-ExcludeDontShow] [<CommonParameters>]

PS C:\Git\PS-Other\platyPS> New-MarkdownHelp -Command Update-MarkdownHelp -AlphabeticParamsOrder -OutputFolder C:\temp\test -ExcludeDontShow

The Syntax block in the generated file shows the following:

Update-MarkdownHelp [-Path] <String[]> [[-Encoding] <Encoding>] [[-LogPath] <String>] [-LogAppend]
 [-AlphabeticParamsOrder] [-UseFullTypeName] [-UpdateInputOutput] [-Force] [-Session <PSSession>]
 [-ExcludeDontShow] [<CommonParameters>]

Note the difference in the -Session paramater.

[sdwheeler]

By design.