-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
PowerShell cmdlets need full documentation #3822
Comments
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. |
@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. |
Yes, at the very least we need the 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 EDIT: Of course, online documentation like winget already has and any other PowerShell-cmdlet also has is also invaluable. |
PSResourceGet is a C# module with help available with platyPS is a module that converts help written in Markdown to XML that could be used here: As mentoined is PS Community Call 2024-02-15, platyPS is under heavy development:
In the call they say Microsoft uses platyPS for almost everything doc related to Microsoft PowerShell cmdlets. Seems PSResourceGet uses platyPS: PSResourceGet also updates to learn.microsoft.com corresponding doc for a given cmdlet if for instance doing Guess this won't come before module is GA and doc on cmdlets is live on learn.microsoft.com. |
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. |
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. |
We're cutting a new build with the help files. |
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. |
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. |
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
The text was updated successfully, but these errors were encountered: