Sync docs changes from docs repo

[sdwheeler]

Sync docs changes from docs repo

• FixesInvoke-ScriptAnalyzer does not report a parse failure in a param() block caused by a missing parameter separator comma. #2192
• ClosesAdd missing Severity entry for Invoke-ScriptAnalyzer docs #2193 - Duplicate PR
  • This PR includes the change from Liam and other edits to that article.
• Fixes AB#591525

[Copilot]

Pull request overview

This PR syncs updated PSScriptAnalyzer documentation from the upstream docs repo, primarily refreshing built-in rule reference pages and cmdlet help pages. It also incorporates the docs change needed to address #2192/#2193 by documenting ParseError as an allowed -Severity value for Invoke-ScriptAnalyzer.

Changes:

• Refresh rule docs to a more consistent structure (default state, clearer descriptions, examples, and “Configure rule” sections).
• Update rules index (docs/Rules/README.md) to a new “Default state” model and add link references for maintainability.
• Update cmdlet docs (including adding New-ScriptAnalyzerSettingsFile and Test-ScriptAnalyzerSettingsFile to the module landing page and documenting ParseError severity).

Reviewed changes

Copilot reviewed 85 out of 85 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/Rules/UseUTF8EncodingForHelpFile.md	Expands rule doc with default state, examples, configuration guidance, and link refs.
docs/Rules/UseUsingScopeModifierInNewRunspaces.md	Refreshes rule description/examples and adds configuration guidance section.
docs/Rules/UseToExportFieldsInManifest.md	Clarifies guidance and adds config/suppression section.
docs/Rules/UseSupportsShouldProcess.md	Rewrites description and adds “Default state” and config guidance.
docs/Rules/UseSingularNouns.md	Reworks description/examples and adds structured parameters section.
docs/Rules/UseSingleValueFromPipelineParameter.md	Adds default state + configuration and clarifies suppression guidance.
docs/Rules/UseShouldProcessForStateChangingFunctions.md	Updates description, adds configure/suppression guidance, and normalizes link refs.
docs/Rules/UsePSCredentialType.md	Expands description and adds configuration guidance section.
docs/Rules/UseProcessBlockForPipelineCommand.md	Improves explanation and adds configure/suppression guidance.
docs/Rules/UseOutputTypeCorrectly.md	Adds default state and config guidance + improves description and link refs.
docs/Rules/UseLiteralInitializerForHashtable.md	Adds default state + configure/suppression guidance and improves examples.
docs/Rules/UseDeclaredVarsMoreThanAssignments.md	Adds default state + configure/suppression guidance and improves explanations.
docs/Rules/UseCorrectCasing.md	Adds example section and rewrites parameters documentation.
docs/Rules/UseConstrainedLanguageMode.md	Major rewrite: adds consolidated restriction/remediation table, config + parameter docs, and link ref normalization.
docs/Rules/UseConsistentWhitespace.md	Adds default state and expands/clarifies parameter descriptions and examples.
docs/Rules/UseConsistentParametersKind.md	Rewrites overview and trims config section (now needs ParametersKind documented).
docs/Rules/UseConsistentParameterSetName.md	Adds default state + guidance/notes and reorganizes configuration section.
docs/Rules/UseConsistentIndentation.md	Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleTypes.md	Adds default state, new examples, and expands parameter descriptions.
docs/Rules/UseCompatibleSyntax.md	Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleCommands.md	Adds default state, examples, and expands parameter documentation.
docs/Rules/UseCompatibleCmdlets.md	Rewrites description/config guidance and adds suppression guidance and link ref.
docs/Rules/UseCmdletCorrectly.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/UseBOMForUnicodeEncodedFile.md	Adds default state + examples and config/suppression guidance; switches to link refs.
docs/Rules/UseApprovedVerbs.md	Adds default state + config/suppression guidance; improves description and examples.
docs/Rules/ShouldProcess.md	Rewrites description, adds default state, and adds config/suppression guidance + link refs.
docs/Rules/ReviewUnusedParameter.md	Adds default state + config/suppression guidance and reorganizes configuration docs.
docs/Rules/ReservedParams.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/ReservedCmdletChar.md	Adds default state, expands reserved character explanation, and adds config/suppression guidance.
docs/Rules/README.md	Replaces rules list table with “Default state” model and link-reference style.
docs/Rules/ProvideCommentHelp.md	Rewrites description and adds structured config + parameter documentation.
docs/Rules/PossibleIncorrectUsageOfRedirectionOperator.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/PossibleIncorrectUsageOfAssignmentOperator.md	Adds detailed explanation + implicit suppression section and adds config/suppression guidance + link refs.
docs/Rules/PossibleIncorrectComparisonWithNull.md	Adds richer explanation/examples and adds config/suppression guidance + link refs.
docs/Rules/PlaceOpenBrace.md	Adds default state, examples, and expands parameter documentation.
docs/Rules/PlaceCloseBrace.md	Adds default state, examples, and expands parameter documentation.
docs/Rules/MissingTryBlock.md	Adds default state, clarifies false-positive note, and normalizes link refs.
docs/Rules/MissingModuleManifestField.md	Adds default state + config/suppression guidance; improves description and adds link refs.
docs/Rules/MisleadingBacktick.md	Adds default state, adds examples, and adds config/suppression guidance.
docs/Rules/InvalidMultiDotValue.md	Adds default state, improves description, and renames configuration section to “Configure rule”.
docs/Rules/DSCUseVerboseMessageInDSCResource.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCUseIdenticalParametersForDSC.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCUseIdenticalMandatoryParametersForDSC.md	Adds default state + config/suppression guidance and improves description (including MOF fencing).
docs/Rules/DSCStandardDSCFunctionsInResource.md	Adds default state, improves examples, and adds config/suppression guidance.
docs/Rules/DSCReturnCorrectTypesForDSCFunctions.md	Adds default state, improves examples, and adds config/suppression guidance.
docs/Rules/DSCDscTestsPresent.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/DSCDscExamplesPresent.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingWriteHost.md	Adds default state + config/suppression guidance; rewrites description and normalizes links.
docs/Rules/AvoidUsingWMICmdlet.md	Adds default state + config/suppression guidance and improves description and examples.
docs/Rules/AvoidUsingUsernameAndPasswordParams.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingPositionalParameters.md	Adds default state, examples, and restructures config + parameter docs.
docs/Rules/AvoidUsingPlainTextForPassword.md	Adds default state + config/suppression guidance and adds SecureString link ref.
docs/Rules/AvoidUsingInvokeExpression.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingEmptyCatchBlock.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingDoubleQuotesForConstantString.md	Adds default state + config/parameter docs and expands description.
docs/Rules/AvoidUsingDeprecatedManifestFields.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md	Adds default state + config/suppression guidance and adds SecretStore recommendation link ref.
docs/Rules/AvoidUsingComputerNameHardcoded.md	Adds default state + config/suppression guidance and improves description/examples.
docs/Rules/AvoidUsingCmdletAliases.md	Adds default state + config/suppression guidance and adds examples.
docs/Rules/AvoidUsingBrokenHashAlgorithms.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidUsingArrayList.md	Adds default state + config/parameter docs and updates references.
docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidTrailingWhitespace.md	Adds default state + examples and config/suppression guidance.
docs/Rules/AvoidShouldContinueWithoutForce.md	Adds default state + config/suppression guidance and adds link refs.
docs/Rules/AvoidSemicolonsAsLineTerminators.md	Adds default state + config/parameter docs and improves description/examples.
docs/Rules/AvoidReservedWordsAsFunctionNames.md	Adds default state + config/suppression guidance and normalizes links.
docs/Rules/AvoidOverwritingBuiltInCmdlets.md	Adds default state, expands description/examples, and updates configuration guidance.
docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidMultipleTypeAttributes.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidLongLines.md	Adds default state, examples, and expands config + parameter docs.
docs/Rules/AvoidInvokingEmptyMembers.md	Adds default state + config/suppression guidance and improves description and references.
docs/Rules/AvoidGlobalVars.md	Adds default state + config/suppression guidance and expands description/examples.
docs/Rules/AvoidGlobalFunctions.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidGlobalAliases.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidExclaimOperator.md	Adds default state, improves description, and expands config/parameter docs.
docs/Rules/AvoidDynamicallyCreatingVariableNames.md	Adds default state, improves description, and restructures config/refs (contains one broken Learn link path).
docs/Rules/AvoidDefaultValueSwitchParameter.md	Adds default state + config/suppression guidance and normalizes links.
docs/Rules/AvoidDefaultValueForMandatoryParameter.md	Adds default state + config/suppression guidance and improves description.
docs/Rules/AvoidAssignmentToAutomaticVariable.md	Adds default state + config/suppression guidance and improves description/examples.
docs/Rules/AlignAssignmentStatement.md	Adds default state, improves examples, and expands config/parameter documentation.
docs/Cmdlets/Test-ScriptAnalyzerSettingsFile.md	Adds/refreshes cmdlet help content (contains a small grammar error in Quiet description).
docs/Cmdlets/PSScriptAnalyzer.md	Bumps help version and adds the new settings-file cmdlets to the landing page list.
docs/Cmdlets/New-ScriptAnalyzerSettingsFile.md	Adds/refreshes cmdlet help content and improves structure/formatting.
docs/Cmdlets/Invoke-ScriptAnalyzer.md	Refreshes examples/output formatting and documents ParseError as a valid -Severity value.
docs/Cmdlets/Invoke-Formatter.md	Minor formatting tweak (blank line after synopsis heading).

Comments suppressed due to low confidence (1)

docs/Rules/UseConsistentParametersKind.md:56

• The Parameters section documents only Enable, but the rule also supports a ParametersKind option. Without documenting it, users can't discover the setting or its valid values.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sdwheeler]

@SeeminglyScience We can skip the failed docs test for now. Please merge.

[sdwheeler]

@SeeminglyScience The docs tests pass now. This latest failure was in an existing test that has passed on previous runs. I think this is a transient problem.

[sdwheeler]

Close/reopen

[sdwheeler]

@SeeminglyScience I reran the build. Now it's failing in a different place in the Windows tests. The docs test pass.