Merge-MarkdownHelp expectation when parameter type varies across versions?
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 28/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- markdown, powershell
- Domain
- documentation, tooling
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.
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?
- Dominant language
- C#
- Stars
- 870
- Forks
- 166
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing 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.
More from PowerShell/platyPS
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
PowerShell/platyPS#868 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
PowerShell/platyPS#857 ·
-
Difficulty 3/5 Half a day Newbie friendliness 68/100
PowerShell/platyPS#867 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 62/100
PowerShell/platyPS#863 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 72/100
PowerShell/platyPS#862 ·
All issues in PowerShell/platyPS
Similar issues
-
status:waiting-for-triage type:bug
Difficulty 1/5 Under an hour Newbie friendliness 84/100
microsoftgraph/msgraph-sdk-dotnet#3194 ·
Maintainers usually reply within 1 day
-
Backend enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
Maintainers usually reply within 1 day
-
UI: money shows the minus sign next to the number, not before the currency (IL -3.0m, not -IL 3.0m)Openarea: sim area: unity enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
eyalgolan/statecraft-israel#1107 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
dimitar-radenkov/Pointframe#271 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
qew21/Genshin-Subtitles#45 ·