📖 [Docs]: .INPUTS and .OUTPUTS corrected to type-name-only format#69
Closed
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Closed
📖 [Docs]: .INPUTS and .OUTPUTS corrected to type-name-only format#69Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Marius Storhaug (MariusStorhaug) wants to merge 2 commits into
Conversation
Both blank-line+description and 4-space-indented description fail markdownlint in PlatyPS-generated docs (MD046 indented code block, or description leaking into the ### heading). The correct format is type name alone - descriptions belong in the generated markdown placeholder. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
added a commit
to PSModule/Template-PSModule
that referenced
this pull request
Jul 25, 2026
## What Updates the scaffold function to use the blank-line description format for `.INPUTS` and `.OUTPUTS` comment-based help: ```powershell .INPUTS None You cannot pipe objects to this function. .OUTPUTS System.String A greeting string for the given name. ``` ## Why The type-name-only format works but gives callers no useful context. Descriptions are required — they should say what is actually piped in or returned, not just repeat the type name. This PR is also a **CI verification**: confirming that the blank-line format (type → blank line → description paragraph) passes PlatyPS + markdownlint in Build-Docs. Previous attempts failed with: - Single-line `System.String. Description.` → MD026 (trailing `.` in heading) - 4-space-indented description → MD046 (indented code block) The blank-line format should produce a clean `### type` heading with the description as body text below — no linting violations. ## Informs - [MSXOrg/docs#69](MSXOrg/docs#69) — if CI passes here, #69 should be closed and the docs updated to require descriptions in this format. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Member
Author
|
Superseded by verified finding: the blank-line format (type → blank line → description paragraph) passes PlatyPS + markdownlint in CI. See PSModule/Template-PSModule#34. Will open a replacement PR requiring descriptions in that format. |
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 comment-based help standards now correctly require type name only in .INPUTS\ and .OUTPUTS\ — no inline description, no description after a blank line.
Fixed: .INPUTS/.OUTPUTS\ description guidance removed
Both previously documented approaches for including a description fail markdownlint in PlatyPS-generated docs:
The canonical format is type name only:
\\powershell
.INPUTS
None
.OUTPUTS
System.Management.Automation.PSCustomObject
\\
Descriptions belong in the generated Markdown file, not in the source comment-based help.
Technical Details
.INPUTSand.OUTPUTSformat rules added to PowerShell function help standards #65 (merged)Related issues