search

PowerShell / platyPS

Write PowerShell External Help in Markdown
MIT License
779 stars 154 forks source link

Merge-MarkdownHelp expectation when parameter type varies across versions? #511

Open chrisda opened 3 years ago

chrisda commented 3 years ago

I wouldn't necessarily call this a bug, but what is the expected Merge-MarkdownHelp result if the Type value of the same parameter in the same cmdlet changes from one version of the product to another (e.g., Exchange 2013 to Exchange 2016)?

For example, the Mailbox parameter in the New-MailboxImportRequest cmdlet. In Exchange 2010 and Exchange 2013, the Type value is MailboxOrMailUserIdParameter. In Exchange 2016 and Exchange 2019, the Type value is MailboxLocationIdParameter. The actual description portions of the parameter is the same across versions.

If you create the following folder structure with the appropriate files:

\Exchange Server 2010\New-MailboxImportRequest.md \Exchange Server 2013\New-MailboxImportRequest.md \Exchange Server 2016\New-MailboxImportRequest.md \Exchange Server 2019\New-MailboxImportRequest.md

And then run the following commands:

$x = "<path>\Exchange Server 2010","<path>\Exchange Server 2013","<path>\Exchange Server 2016","<path>\Exchange Server 2019"
Merge-MarkdownHelp -Path $x -OutputPath "<path>\platyPSissue\Merged" -ExplicitApplicableIfAll

platyPSIssue3.zip

You'll see in the resulting attached output file, the Type value of the Mailbox parameter is MailboxOrMailUserIdParameter only (the 2010/2013 values). Shouldn't the Mailbox parameter contain multiple YAML sections like this?

Type: MailboxOrMailUserIdParameter
Parameter Sets: (All)
Aliases:
Applicable: Exchange Server 2010, Exchange Server 2013

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
Type: MailboxLocationIdParameter
Parameter Sets: (All)
Aliases:
Applicable: Exchange Server 2016, Exchange Server 2019

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False

And what about parameter sets in the SYNTAX section? As you can see, the Mailbox parameter only has the MailboxOrMailUserId parameter:

## SYNTAX

New-MailboxImportRequest [-Mailbox] <MailboxOrMailUserIdParameter> ...

Shouldn't there be two parameter sets? And what to call them and/or how to duplicate and tack and identifier on the end of the parameter set name like this?

## SYNTAX

### MailboxOrMailUserId

New-MailboxImportRequest [-Mailbox] <MailboxOrMailUserIdParameter> ...

### MailboxLocationId

New-MailboxImportRequest [-Mailbox] <MailboxLocationIdParameter> ...

And of course, this would change the Applicable values in the YAML sections in the parameter description.

Is this known or expected behavior?

theJasonHelmick commented 3 years ago

@chrisda - the result you're experiencing today is by design. To make this work would probably require a redesign of the applicable feature which is not in-scope for the 2.0 release. I'm adding this to our Future-consider list for future releases.