📖 [Docs]: OutputType parameter set scoping and parameter set naming rules strengthened#66
Merged
Marius Storhaug (MariusStorhaug) merged 2 commits intoJul 25, 2026
Conversation
…ing rules - Add '[OutputType] and parameter sets' subsection after the Section structure code example, covering single-type (no scoping) vs per-set scoping with a concrete powershell snippet and the OutputType/.OUTPUTS contract rule. - Replace the weak parameter set naming bullet with a full rule: names appear verbatim in Get-Help syntax output, must be readable English phrases (ByName, ByPath, WithCredential, AsSession style), lists explicitly unacceptable names, and mandates DefaultParameterSetName when multiple sets exist. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Update the [OutputType] code example to use 'By display name' and
'From file path' instead of 'ByName'/'ByPath', demonstrating that
PowerShell parameter set names support spaces and read more naturally
in Get-Help output that way.
Strengthen the naming rule bullet to lead with spaced prose names as
the preferred form ('By display name', 'From file path', 'As computer
name') and note explicitly that spaces are supported and encouraged.
PascalCase single-word names remain acceptable as a fallback.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
July 25, 2026 12:51
Marius Storhaug (MariusStorhaug)
deleted the
feat-outputtype-parameterset-naming
branch
July 25, 2026 12:51
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PowerShell coding standards now precisely cover two tightly coupled topics: how to scope
[OutputType]when parameter sets return different types, and what makes a parameter set name acceptable.New:
[OutputType]scoping per parameter setA new subsection "
[OutputType]and parameter sets" is added directly after the Section structure code example. It explains when to use a single unscoped[OutputType](all sets return the same type) versus per-set scoping usingParameterSetName, includes a runnable snippet showing both[OutputType]attributes alongside[CmdletBinding(DefaultParameterSetName = ...)], and states the contract: types in[OutputType]must match.OUTPUTSin comment-based help.Changed: Parameter set naming rule
The previous bullet ("Name every parameter set with an intent-revealing name … never
Defaultor__AllParameterSets") has been replaced with a precise rule that explains why: parameter set names appear verbatim inGet-Helpsyntax output and are read by callers, not just developers. The rule now lists the acceptable patterns (ByName,ByPath,ByLiteralPath,ByGuid,WithCredential,AsComputerName,AsSession), enumerates explicitly unacceptable names (Default,__AllParameterSets,__DefaultParameterSet,ParameterSetA,Set1,Mode1), and makesDefaultParameterSetNamemandatory when multiple sets exist.Technical Details
src/docs/Coding-Standards/PowerShell/Functions.md[OutputType]scoping is meaningless without well-named parameter sets to reference.Related issues