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?

[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.