Add 'Get-Help -Parameter' recommendation to the auto-generated REMARKS section - #28015
stareezy (stareezy-1) wants to merge 1 commit into
Conversation
…S section The auto-generated REMARKS section recommends the -Examples, -Detailed, -Full, and -Online switches, but does not mention -Parameter. Add a ParameterHelpInfo resource and append the -Parameter <parametername> recommendation to every formatter block that emits the REMARKS suggestion list, covering cmdlet help (default and -Detailed views) as well as the DSC resource and class help views. The new string is added to the neutral HelpDisplayStrings.resx; the localization pipeline propagates it to the language-specific files. Fix PowerShell#26098
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
There was a problem hiding this comment.
🟡 Changes recommended
DSC/class views advertise unsupported parameter lookup, and those views lack regression coverage.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds -Parameter <parametername> recommendations to autogenerated Get-Help remarks.
Changes:
- Adds the localized parameter-help resource string.
- Updates standard, DSC, and class help formatters.
- Adds command-help regression tests.
File summaries
| File | Summary |
|---|---|
test/powershell/engine/Help/HelpSystem.Tests.ps1 |
Tests default and detailed command-help recommendations; DSC/class views remain uncovered. |
src/System.Management.Automation/resources/HelpDisplayStrings.resx |
Adds the parameter-help prompt. |
src/System.Management.Automation/FormatAndOutput/DefaultFormatters/HelpV3_format_ps1xml.cs |
Adds recommendations to DSC and class views, where -Parameter lookup is unsupported. |
src/System.Management.Automation/FormatAndOutput/DefaultFormatters/Help_format_ps1xml.cs |
Adds the recommendation to standard command-help views. |
Review details
Suppressed comments (2)
src/System.Management.Automation/FormatAndOutput/DefaultFormatters/HelpV3_format_ps1xml.cs:904
- This is a
DscResourceHelpInfoview, but the advertised command cannot retrieve DSC property help:-Parameteris not supported for theDscResourcecategory, andMamlCommandHelpInfo.GetParameter()only reads theparameterscollection while these views render DSCProperties. As a result, this recommendation sends users to an error/empty result; remove it from the DSC views or implement DSC parameter support before advertising it.
.AddText(HelpDisplayStrings.ParameterHelpInfo)
.AddText(@"""")
.AddScriptBlockExpressionBinding(@"""Get-Help "" + $_.Details.Name + "" -Parameter <parametername>""")
.AddText(@"""")
.AddNewline()
src/System.Management.Automation/FormatAndOutput/DefaultFormatters/HelpV3_format_ps1xml.cs:904
- The regression test exercises only the
MamlCommandHelpInfodefault and detailed views. None of the sixDscResourceHelpInfo/PSClassHelpInfoviews added here are covered, so a malformed binding or a missing line in these branches could pass the new test unnoticed. Please add representative DSC-resource and class help assertions for the relevant default/detailed (and full, where this change also applies) views.
.AddText(HelpDisplayStrings.ParameterHelpInfo)
.AddText(@"""")
.AddScriptBlockExpressionBinding(@"""Get-Help "" + $_.Details.Name + "" -Parameter <parametername>""")
.AddText(@"""")
.AddNewline()
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
| .AddText(HelpDisplayStrings.ParameterHelpInfo) | ||
| .AddText(@"""") | ||
| .AddScriptBlockExpressionBinding(@"""Get-Help "" + $_.Details.Name + "" -Parameter <parametername>""") | ||
| .AddText(@"""") | ||
| .AddNewline() |
|
stareezy (@stareezy-1) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
Sean Wheeler (sdwheeler)
left a comment
There was a problem hiding this comment.
The text of the changes look good to me. Someone else should review the Copilot comment and decide if it needs to be addressed or ignored.
PR Summary
Fix #26098 —
Get-Helpoutput's auto-generatedREMARKSsection recommends-Examples,-Detailed,-Full, and-Online, but not-Parameter. This adds the missing-Parameter <parametername>recommendation so users can discover parameter help directly from the default and-Detailedviews.PR Context
Get-Help <command> -Parameter <name>shows focused help for a single parameter, and the auto-generatedREMARKSsection is where the otherGet-Helpswitches are surfaced. The suggestion list is emitted from the help formatting definitions, so the new line is added to every block that renders it.PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerChanges
resources/HelpDisplayStrings.resx: newParameterHelpInfostring (For parameter help, type:). Added to the neutral resource file; the localization pipeline propagates it to the language-specific files.Help_format_ps1xml.cs: added the recommendation to theDefaultCommandHelpandVerboseCommandHelp(detailed) remarks blocks.HelpV3_format_ps1xml.cs: added the recommendation to the six DSC resource and class help remarks blocks.test/powershell/engine/Help/HelpSystem.Tests.ps1: new testValidate 'Remarks' recommends parameter helpcovering the default and-Detailedviews.Testing
Default view after the change:
Pester:
test/powershell/engine/Help/HelpSystem.Tests.ps1— 85 passed, 0 failedtest/powershell/engine/Help(whole folder) — 351 passed, 0 failed