Missing information on `ParameterAttribute`'s `DontShow` property and its side effects

[surfingoldelephant]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters#parameter-attribute
https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/parameter-attribute-declaration

Summary

ParameterAttribute has a DontShow property, which is currently undocumented in about_Functions_Advanced_Parameters and Parameter Attribute Declaration.

A naive public code search for DontShow usage yields thousands of results, so I think documenting this property/argument is warranted given its usage by the community. In v7.5, it's used by 5 commands that ship with PowerShell, all of which have obscure user-facing implications from its usage.

Details

DontShow hides the associated parameter from tab completion results/code editor IntelliSense.

• The .NET documentation states:

  This is primarily to be used in functions that are implementing the logic for dynamic keywords.

• However, in practice, DontShow is typically used to assist backwards compatibility for a command (i.e., in scenarios where an obsolete parameter cannot be removed, DontShow helps prevent new use by hiding it). This use case is applicable to some commands shipped with PowerShell (see below).

DontShow has the following side effects:

• Affects all parameter sets for the associated parameter, even if there's a parameter set in which DontShow is unused.
• Hides common parameters from tab completion results/code editor IntelliSense.
  • This applies to common parameters, but not optional common parameters (-WhatIf, -Confirm, -UseTransaction).
  • In v7.5, there are 5 commands shipped with PowerShell that use DontShow to hide obsolete parameters and thus suffer from a lack of common parameter completions.
    • ConvertTo-Csv (-NoTypeInformation)
    • Export-Csv (-NoTypeInformation)
    • Format-Hex (-Raw)
    • Invoke-RestMethod (-UseBasicParsing)
    • Invoke-WebRequest (-UseBasicParsing)

DontShow does not:

• Affect Get-Help or Get-Command output.

Example:

function TestFunction { [CmdletBinding(SupportsShouldProcess)] param ([Parameter()] $DontShow, $Show) }
TestFunction -<Ctrl+Tab>
# DontShow     WhatIf      Verbose     ErrorAction     InformationAction     ErrorVariable ...       
# Show         Confirm     Debug       WarningAction   ProgressAction        WarningVariable ...     

function TestFunction { [CmdletBinding(SupportsShouldProcess)] param ([Parameter(DontShow)] $DontShow, $Show) }
TestFunction -<Ctrl+Tab>
# Show     WhatIf   Confirm

Get-Command TestFunction -Syntax
# TestFunction [[-DontShow] <Object>] [[-Show] <Object>] [-WhatIf] [-Confirm] [<CommonParameters>]

Suggested Fix

• Add DontShow to the aforementioned documents and explain the typical use case(s) with an example.
• Note the unfortunate side effects of its use (especially on common parameters).
  • List the commands shipped with PowerShell in v7.5 that are affected and note that common parameters can still be used with these commands.
  • Note: Windows PowerShell v5.1 does not ship any commands with DontShow.