[NewTopic] Provide better usage descriptions in Cmdlet.ShouldProcess

[aydeisen]

https://docs.microsoft.com/en-us/dotnet/api/system.management.automation.cmdlet.shouldprocess?view=powershellsdk-1.1.0

Normally, the API documentation is straightforward about the different overloads in a method, and whether they augment more minimalist overloads, or are used to cover different purposes

For the life of me, I can't figure out when I would use ShouldProcess(String, String, String, ShouldProcessReason) or ShouldProcess(String, String, String) or why, instead of the other two. The examples not being in formatted code blocks isn't really helping either.

Both of those methods say This variant allows the caller to specify the complete text describing the operation, rather than just the name and action. I assume the 'caption' parameter is supposed to allow a more freeform text over the canned text when only providing the 'target' or both 'target' and 'action'. But why would I use 'caption' when it says may be displayed by some hosts, but not all, and the overloads with only 'action'/'target' parameters don't document such a limitation?

Additionally, as this document is related to PowerShell, I don't understand why 'ShouldProcessReason' would ever be needed. ShouldProcess would only be used if CmdletBinding() is called with SupportsShouldProcess=$True, which then exposes the -WhatIf parameter. What use case is there to then specify 'ShouldProcessReason'?

[mairaw]

I'm sorry we missed this feedback earlier @aydeisen. @dend who owns Powershell docs?

And why the Edit button goes to a private repo? And it's also missing breadcrumbs.

[dend]

This would be for @joeyaiello and team.

[mairaw]

Thanks @dend. Can you help with the breadcrumb?

@joeyaiello where can I move this issue to since this is not about .NET documentation?

[joeyaiello]

@mairaw please move it over to https://github.com/PowerShell/PowerShell-Docs

/cc @sdwheeler you want these issues in PowerShell-Docs as opposed to pscore-docs-dotnet, right?

[mairaw]

Thanks @joeyaiello. Moved issue to MicrosoftDocs/PowerShell-Docs#2499.

@dend there's also the issue with the garbled examples on that page. Not sure if this is a bug for your team to look at as well.

[sdwheeler]

@joeyaiello @mairaw @dend I don't own this content, though we should have a discussion to figure out if I should. But there are three problems being discussed in this issue.

1. The content question about the SDK and how to use the ShouldProcess() method. This is not a PowerShell-Docs issue.
2. The breadcrumb and edit link problem.
3. Formatting problem

Someone from the product team needs to answer the SDK question. The other two would go to the repo/content owner.

[aydeisen]

@sdwheeler: I had the same question as #1. The document I'm citing is in the root URL https://docs.microsoft.com/en-us/dotnet, which is why I filed the issue here. It is not in the reciprocal powershell-docs (about_functions_advanced_methods, I believe), so I wasn't clear why this issue needed to be recategorized

[mairaw]

The root URL https://docs.microsoft.com/en-us/dotnet/api/ encompasses too many products. This repo is only about .NET itself (.NET Core, .NET Framework, etc.)

The content for the PowerShell ref docs is coming from https://github.com/MicrosoftDocs/powershell-docs-sdk-dotnet. That repo is private and I don't know who owns.