Repository navigation
Give the script a generated reference, a hero and CI - #1
Merged
Merged
Conversation
The script had no documented parameters anywhere: readers had to open a 1300-line
file to find out what -InactiveDays does. It now has a reference generated from
its own comment-based help, the same way the module-shaped tools do it, so the
published parameter table cannot drift from the script people download.
Two real bugs in the help, found while generating from it:
- both examples named Get-AppLifecycleAnalysis.ps1, a file that does not exist
- the .NOTES block carried Author/Site/License bookkeeping and the description
a nested bullet list, neither of which survives being rendered as a page
The help is now prose that reads the same in the terminal and on the web, with
four examples that run as written.
Also fixed while the analyzer was pointed at the file:
- the catch around federated credentials was empty, so an app that refused to
hand them over showed as having none. On an audit that is a wrong answer
rather than a missing one; failures are counted and warned about now.
- added #Requires -Version 7.0. The script already used $IsWindows, so it was
PowerShell 7 only in fact; now it says so instead of failing strangely.
CI runs PSScriptAnalyzer and checks that the reference is current. The analyzer
settings follow the two-space convention the script is written in rather than
importing another repository's, and exclude two rules with the reason in place.
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
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.
The script had no documented parameters anywhere. Readers had to open a 1300-line file to find out what
-InactiveDaysdoes. It now has a reference generated from its own comment-based help — the same approach the module-shaped tools use — so the published parameter table cannot drift from the script people download.Two real bugs in the help
.EXAMPLEblocks namedGet-AppLifecycleAnalysis.ps1, a file that does not exist. Anyone copying them got "file not found"..NOTEScarriedAuthor/Site/Licensebookkeeping and.DESCRIPTIONa nested bullet list. Neither survives being rendered as a page.The help is now prose that reads the same in the terminal and on the web, with four examples that run as written.
Two found by pointing the analyzer at the file
catcharound federated credentials was empty, so an app that refused to hand them over showed as having none. On an audit that is a wrong answer rather than a missing one — failures are counted and warned about now.#Requires -Version 7.0. The script already used$IsWindows, so it was PowerShell 7 only in fact; now it says so instead of failing strangely.CI
PSScriptAnalyzer plus
New-CommandReference.ps1 -Check, which is what stops the reference drifting. The settings follow the two-space convention this script is written in rather than importing another repository's, and exclude two rules with the reason written next to them:PSAvoidUsingWriteHost— this is an interactive console script; the progress is for a person.PSUseBOMForUnicodeEncodedFile— the BOM exists for Windows PowerShell 5.1, which#Requires -Version 7.0already rules out.Verified locally:
PSScriptAnalyzer: clean,-Checkpasses,Get-Helpstill resolves the synopsis and all six parameters with#Requiresabove the help block.The hero renders from
docs/images/hero.source.html; the tools site gets a copy in the companion PR.