PowerShell / PowerShell/platyPS

Merge-MarkdownHelp expectation when parameter type varies across versions?

Open
#511 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Area-MergeMarkdown
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

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?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.