Repository navigation
[documentation-writing-alignment] Make native help match framework command contracts #574
Description
Context and request
Contributors need native-help examples and export descriptions that match the commands in Process-PSModule. The prose review in #558 preserves exact examples and runtime contracts, so these discrepancies remain separate work. The baseline is 64ffb1d87f86bd5d487891fdb140b78385a00531; #570 changes prose but preserves the examples.
Evidence and expected result
| Source | Observed help | Local implementation |
|---|---|---|
.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1 |
Example uses -SourceFolderPath and -OutputFolderPath |
Parameters are ModuleName, ModuleSourceFolder, and ModuleOutputFolder |
.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1 |
Example uses -SourceFolderPath and -OutputFolderPath |
Parameters are ModuleName, ModuleOutputFolder, ModuleVersion, and ModulePrerelease |
.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1 |
Example uses -SourceFolderPath and -OutputFolderPath; description restricts cmdlets to cmdlets/public |
Parameters are ModuleName and ModuleOutputFolder; Get-PSModuleCmdletsToExport reads CmdletsToExport from the manifest |
.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 |
Import-PSModule and Install-PSModule examples use -SourceFolderPath and -ModuleName |
Both use Path; only Install-PSModule also has PassThru |
.github/actions/Install-PSModule/src/PSModule/PSModule.psm1 |
Get-ModuleManifest example calls Get-PSModuleManifest |
The local command is Get-ModuleManifest |
.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1 |
Example output lists Book and BookList |
The function emits objects with Type and Name properties |
Native-help coverage also has substantive gaps. For example, Build-PSModule has no example or input/output section; Update-PSModuleManifestAliasesToExport has only a synopsis; many index helpers have no examples or input/output sections. Do not fill these sections with copied or generic text. Establish the local contract and useful examples first.
Acceptance criteria:
- Each affected example uses the local command name and valid parameters.
- Examples and stated output shapes agree with isolated behavior checks.
- The root-module cmdlet export description states the actual contract, with any intended contract change handled separately.
- Any added help section explains the local command rather than repeating generic scaffolding.
- Runtime implementation, public names, fixtures, and action input values remain unchanged unless a separately approved behavior change requires them.
Technical decisions
Use the native PowerShell parser and Get-Help to retain help association and syntax. Use isolated temporary modules/data for examples that install modules, write files, or query GitHub. Do not run state-changing examples against the contributor's module installation. Apply the pinned writing sources recorded in #558. Recheck live PR ownership before editing.
Implementation plan
- Inventory the affected examples, native help sections, local parameters, and output types.
- Add narrow checks that demonstrate the invalid examples or output claims before editing help.
- Resolve the intended cmdlet-export contract against the build implementation and module layout guidance.
- Revise the affected help and examples in one focused draft PR; retain runtime code unless separately authorized.
- Run parser, rendered-help, example, and behavior-preservation checks; record exact before/after evidence.
Activity
[-]Make native help match framework command contracts[/-][+][documentation-writing-alignment] Make native help match framework command contracts[/+]MariusStorhaug commentedon Nov 4, 2026
Added the shared documentation-writing campaign prefix. The native Task type, evidence, scope, implementation plan, labels, and source ownership are unchanged. No implementation or PR change is included.
MariusStorhaug commentedon Nov 4, 2026
Additional reserved-helper contract accuracy evidence is retained in the #564 audit (#564 (comment)): existing release-note wording versus pushed-commit-message fallback, five-attempt loop versus retry wording, and imprecise array/PSSemVer output declarations. These are not certified or changed by the grammar-only delivery. Verify exact source contracts before extending the owning native-help accuracy correction. The independent all-release retrieval defect is #583, not a documentation-only fix. No existing source scope, implementation or lifecycle is changed by this evidence link.