Add 'Get-Help -Parameter' recommendation to the auto-generated REMARKS section - #28015
stareezy (stareezy-1) wants to merge 2 commits 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() |
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.
|
This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days. |
|
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”),
|
PR Summary
Fix #26098 by recommending
Get-Help <command> -Parameter <parametername>in the auto-generated REMARKS for command help's default and detailed views.PR Context
Adds the localized
ParameterHelpInforesource and uses it inDefaultCommandHelpandVerboseCommandHelp. DSC-resource and class views are unchanged because those categories do not support-Parameterlookup.Tests verify both command-help recommendations and all six DSC/class default, detailed, and full views. The latter cases check that existing recommendations remain without advertising unsupported parameter help. All six failed against the original PR binary and pass after the correction.
PR Checklist
.h,.cpp,.cs,.ps1and.psm1files have the correct copyright headerValidation
11.0.100-rc.1.26425.128, using cached packages and the repository's Debug/net11.0/osx-arm64 publish options.Start-PSPester -Path test/powershell/engine/Help -SkipTestToolBuild -ThrowOnFailure -Terse: 259 passed, 0 failed, 146 skipped, 2 pending. Includes the new formatter cases and existing command-help tests. This local run excludes slow and sudo-required tests; skipped/pending cases are not claimed as verified.git diff --checkpasses.AI assistance was used for implementation and test development.