PowerShell / ConsoleGuiTools

Modules that mix PowerShell and GUIs/CUIs!
https://www.powershellgallery.com/packages/Microsoft.PowerShell.ConsoleGuiTools
MIT License
776 stars 59 forks source link

Add HelpMessage for command-line Parameters #172

Closed tig closed 2 years ago

tig commented 2 years ago

Summary of the new feature / enhancement

Today:

$ help ocgv

NAME
    Out-ConsoleGridView

SYNTAX
    Out-ConsoleGridView [-InputObject <psobject>] [-Title <string>] [-OutputMode {None | Single | Multiple}] [-Filter <string>] [-MinUI] [<CommonParameters>]

PARAMETERS
    -Filter <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false

    -InputObject <psobject>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       true (ByValue)
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false

    -MinUI

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false

   ...

This should be:

$ help ocgv

NAME
    Out-ConsoleGridView

SYNTAX
    Out-ConsoleGridView [-InputObject <psobject>] [-Title <string>] [-OutputMode {None | Single | Multiple}] [-Filter <string>] [-MinUI] [<CommonParameters>]

PARAMETERS
    -Filter <string>
        Sets the initial value for the filter in the GUI. The filter uses regular expressions. 

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false

    -InputObject <psobject>
        This parameter specifies the current pipeline object.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       true (ByValue)
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false

    -MinUI
        If specified, no window frame, filter box, or status bar will be displayed in the GUI.

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
   ...

Proposed technical implementation details (optional)

This is accomplished by adding a HelpMessage = to the [Parameter()] attributes of each parameter:


        /// <summary>
        /// Sets the whether "minimum UI" mode will be enabled
        /// </summary>
        [Parameter(HelpMessage = "If specified, no window frame, filter box, or status bar will be displayed in the GUI.")]
        public SwitchParameter MinUI { set; get; }
MrFly72 commented 2 years ago

Maybe adding this to the function might be great. Did this for all modules I wrote and it is easier then doing extra helpfile in my eyes: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help