Fixes #1722 - Update cmdlet docs for 1.20.0 - #1726
Conversation
Sorry, something went wrong.
|
Looks like cmdlet help tests are failing: ##[error] [-] Cmdlet help.gets example help from 21ms (18ms|2ms)
##[error] Expected a value, but got $null or empty.
##[error] at ($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
##[error] at <ScriptBlock>, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
##[error] [-] Cmdlet help.gets example help from 9ms (7ms|2ms)
##[error] Expected a value, but got $null or empty.
##[error] at ($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
##[error] at <ScriptBlock>, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
##[error] [-] Cmdlet help.gets example help from 8ms (7ms|2ms)
##[error] Expected a value, but got $null or empty.
##[error] at ($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
##[error] at <ScriptBlock>, /home/vsts/work/1/s/Tests/Engine/ModuleHelp.Tests.ps1:121
|
Sorry, something went wrong.
|
Rob Holt (@rjmholt) I checked to see if there were tests. I couldn't find them. I will take another look and fix them. |
Sorry, something went wrong.
|
Rob Holt (@rjmholt) I removed the test for Remarks in the example. Remarks are optional. The only thing we need to validate is that there is a code block in the example. |
Sorry, something went wrong.
|
|
||
| # Should be at least one example description | ||
| It "gets example help from $commandName" -TestCases $testCases { | ||
| ($Help.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty | ||
| } |
There was a problem hiding this comment.
I think we're better off not removing tests like this if we can avoid it — it's a nice bar on doc quality that we require examples.
If docs are just being updated, what caused this to fail?
Sorry, something went wrong.
There was a problem hiding this comment.
I agree, I wouldn't normally want to remove a test but the Remarks are optional.
The test broke because the Remarks were moved. In some cases, the Remark was incorporated into the Example title. In others it was move before the code block as an intro.
Sorry, something went wrong.
There was a problem hiding this comment.
For higher quality, we should be testing the following:
- every parameter of a cmdlet exists in the markdown
- each parameter has description
- the markdown does not contain any parameters that the cmdlet doesn't have
Sorry, something went wrong.
PR Summary
Fixes #1722 - Prepare cmdlet reference for publication on docs.microsoft.com
PR Checklist