PowerShell cmdlets need full documentation

[jdhitsolutions]

Brief description of your issue

I'm sure this is on the to-do list, but the PowerShell commands need complete documentation. This includes descriptions, parameter information, and examples. Or is the documentation available as open-source repo where the community could help?

Edits by @denelon

• #4673
• #4690

[denelon]

We will probably keep the documentation here at GitHub until the PowerShell modules are announced as GA (Generally Available). Once they are GA, we will add a section to Microsoft Learn. Both locations are open-source.

[denelon]

@jdhitsolutions The source for the PowerShell modules is here at GitHub.

[jdhitsolutions]

That doesn't really help. As far as I can tell, the module has no intermediate markdown documents or external help files like you would get with the Platyps module. The help we get now is only what PowerShell automatically generates from the syntax and code. To be clear, I'm talking about command documentation for the user.

[jantari]

Yes, at the very least we need the SYNOPSIS for each cmdlet and PARAMETER descriptions for every parameter. These are what I reference the most at least. For a PowerShell function or a module written in PowerShell, this is easily done with comment-based help, e.g. just paste this into PowerShell:

function Find-WinGetPackage2 {
  <#
    .SYNOPSIS
    This cmdlet does something or other

    .PARAMETER Command
    Specifies the command to <whatever>

    .PARAMETER Count
    Specifies the count of something something
  #>
  [CmdletBinding()]
  Param (
    [string]$Command,
    [Uint32]$Count
  )

  Write-Output $Command
  Write-Output $Count
}

Get-Help Find-WinGetPackage2 -Detailed

Unfortunately I have never published a binary (C#) module but I know it is possible to add the same help-metadata to those. These examples use triple-slash /// <summary> comments, maybe that's all it takes?

EDIT: Of course, online documentation like winget already has and any other PowerShell-cmdlet also has is also invaluable. Get-Help CmdletName -Online is also supposed to go directly to the correct docs page on learn.microsoft.com

[o-l-a-v]

PSResourceGet is a C# module with help available with Get-Help (might have to do Update-Help -Module 'Microsoft.PowerShell.PSResourceGet' first):

• https://github.com/PowerShell/PSResourceGet

---

platyPS is a module that converts help written in Markdown to XML that could be used here:

• https://github.com/PowerShell/platyPS

As mentoined is PS Community Call 2024-02-15, platyPS is under heavy development:

• Note: https://github.com/PowerShell/PowerShell-RFC/blob/master/CommunityCall/notes/20240215_Notes.md
• Video with timestamp: https://www.youtube.com/watch?v=OJlJJnCtFrQ&t=1670s

In the call they say Microsoft uses platyPS for almost everything doc related to Microsoft PowerShell cmdlets.

Seems PSResourceGet uses platyPS:

• https://github.com/search?q=repo%3APowerShell%2FPSResourceGet%20platyps&type=code

---

PSResourceGet also updates to learn.microsoft.com corresponding doc for a given cmdlet if for instance doing Get-Help -Name 'Get-PSResource' -Online. Winget does not have this yet, so Get-Help -Name 'Assert-WinGetPackageManager' -Online gives Get-Help: The online version of this Help topic cannot be displayed because the Internet address (URI) of the Help topic is not specified in the command code or in the help file for the command..

Guess this won't come before module is GA and doc on cmdlets is live on learn.microsoft.com.

[ThomasNieto]

@denelon there is a PR to include Microsoft.WinGet.CommandNotFound in PowerShell. That module requires this one so it really needs PowerShell based help and ideally updateable via #3206.

[denelon]

I met with some of our PowerShell folks to learn more about how we should be documenting our modules. We will be using platyPS. It's going to take some time to build this out and get it added to the pipeline. I'll add links to discrete Issues for each module to the top of this Issue as the primary one to track the request. We'll also be onboarding to Microsoft Learn so the documentation can be updated there as well.

[denelon]

I took a first pass at the platyPS documentation. I'd like to get it merged in so the engineering team can work on the build pipeline steps to get it included in the next build when we publish the modules.

I found several bugs and filed issues for them. Feel free to review the PR and tell me what I did wrong, but I wanted to go ahead and get the .md files in so others could contribute to improve them.

I'm expecting I'll also need to update a README somewhere with links to the content for platyPS and MAMAL over at Microsoft Learn.

[denelon]

We're cutting a new build with the help files.

[denelon]

Microsoft.WinGet.Client with new help is out:

https://www.powershellgallery.com/packages/Microsoft.WinGet.Client/1.9.2411

We need to tackle Microsoft.WinGet.Configuration and Microsoft.WinGet.DSC next.

[denelon]

The help files are now included in the build.

We still have plenty of work to improve the cmdlets and close gaps between the WinGet CLI, but I'm hoping this "helps" make them more understandable.