PowerShell / PowerShell/platyPS
Merge-MarkdownHelp expectation when parameter type varies across versions?
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 871
- Forks
- 166
- Avg merge
- 21h 17m
- Merged PRs (30d)
- 1
Description
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
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?
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the supplied platyPSIssue3.zip and reproduce Merge-MarkdownHelp using the four Exchange Server directories and New-MailboxImportRequest.md files. Inspect the merged output for the Mailbox parameter and SYNTAX section; done requires a documented, consistent result for differing Type values, parameter sets, and Applicable values across versions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, powershell
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100