Addition of Comment Based help

[brianmccarty]

Addition of comment based help and external help to module

I'd like to start building comment based help into each function, additionally building of a docs folder with markdown extractions of that help

I am willing to build out file by file until each function includes help.

I'm interested in preferences for formatting of said help. I usually include the help within my functions for easy roll-up.

For example

function Verb-Noun {
<#
.SYNOPSIS
    Short description
.DESCRIPTION
    Long description
.PARAMETER Name
    Specifies a path to one or more locations.
.EXAMPLE
    C:\PS>
    Example of how to use this cmdlet
.EXAMPLE
    C:\PS>
    Another example of how to use this cmdlet
.NOTES
    General notes
#>
    [CmdletBinding()]
    param (
        
    )  
    begin {
    }  
    process {
    }
    end {
    }
}

[adrianwells]

@brianmccarty that sounds like a helpful idea. Your example looks reasonable. There may be some overlap with the IT Glue API documentation and the Wiki but feel free to build some out (maybe a branch on your fork) and submit as a PR. How does that sound?
FYI @CalebAlbers

[brianmccarty]

The purpose would not be to replace or even supplement the API documentation, but to provide get-help of a commands from within Powershell for usage of the commands. And to populate the docs folder in the Github repo with help to enable a link for the -online command to allow for web based documentation.

The wiki is fine, but IMO it isn't useful to the coder. Putting the examples, usage, descriptions etc into the functions themselves provides the user with all the information at their finger tips.

The current help (see below) of the commands only provides the Powershell parsed help, with no actual examples of commands and usage. I believe it would be valuable to have enhanced descriptions of the parameters, examples, etc.

I'll build out an example in my fork, and post of follow up to this item for comments.

Current Get-Help of Get-ITGlueOrganizations

get-help Get-ITGlueOrganizations -Full

NAME
    Get-ITGlueOrganizations

SYNTAX
    Get-ITGlueOrganizations [-filter_id <long>] [-filter_name <string>] [-filter_organization_type_id <long>] [-filter_organization_status_id <long>] [-filter_created_at
    <string>] [-filter_updated_at <string>] [-filter_my_glue_account_id <long>] [-filter_exclude_id <long>] [-filter_exclude_name <string>]
    [-filter_exclude_organization_type_id <long>] [-filter_exclude_organization_status_id <long>] [-filter_range <string>] [-filter_range_my_glue_account_id <long>] [-sort
    {name | id | updated_at | organization_status_name | organization_type_name | created_at | short_name | my_glue_account_id | -name | -id | -updated_at |
    -organization_status_name | -organization_type_name | -created_at | -short_name | -my_glue_account_id}] [-page_number <long>] [-page_size <int>]  [<CommonParameters>]

    Get-ITGlueOrganizations [-id <long>]  [<CommonParameters>]


PARAMETERS
    -filter_created_at <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_exclude_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_exclude_name <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_exclude_organization_status_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_exclude_organization_type_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_my_glue_account_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_name <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_organization_status_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_organization_type_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_range <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_range_my_glue_account_id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -filter_updated_at <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -id <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           show
        Aliases                      None
        Dynamic?                     false

    -page_number <long>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -page_size <int>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    -sort <string>

        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           index
        Aliases                      None
        Dynamic?                     false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).


INPUTS
    None


OUTPUTS
    System.Object

ALIASES
    None


REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer. It is displaying only partial help.
        -- To download and install Help files for the module that includes this cmdlet, use Update-Help.

[CalebAlbers]

I'm all for this. It's been on the back burner too long, and frankly needs to be in place. I'm fine with the layout suggested, with the suggestion of adding a .LINK keyword that links to the IT Glue documentation and any relevant wiki articles:

<#
.SYNOPSIS
    Short description
.DESCRIPTION
    Long description
.PARAMETER Name
    Specifies a path to one or more locations.
.EXAMPLE
    C:\PS>
    Example of how to use this cmdlet
.EXAMPLE
    C:\PS>
    Another example of how to use this cmdlet
.NOTES
    General notes
.LINK
    https://api.itglue.com/developer
    https://github.com/itglue/powershellwrapper/...
#>

I'll start working this week on that. Feel free to contribute anything you might already have.

Thanks!

[Celerium]

If comment-based help is still wanted I can take this action. I could get something together today or tomorrow for all the functions. You can reference my recent pull request #139 to see an example of what the help could look like.

Do we want to use PlatyPS and Github pages to help display documentation around the functions? As a reference in one of my recent projects, I combined the comment-based help with PlatysPS & Github pages to generate markdown files then using a simple Jekyll template and GitHub action I can display all the help files online. It's almost fully automated though at this time I haven't quite figured out how PowerShell external help works.

• S1 Wrapper
• docs

@CalebAlbers I made a slight tweak from the recommendation above to separate out the .LINK. When there are two URLs in the same .LINK Get-Help -online will combine the URLs.

https://api.itglue.com/developer/#logshttps://github.com/itglue/powershellwrapper

<#
.SYNOPSIS
    Short description
.DESCRIPTION
    Long description
.PARAMETER Name
    Specifies a path to one or more locations.
.EXAMPLE
    C:\PS>
    Example of how to use this cmdlet
.EXAMPLE
    C:\PS>
    Another example of how to use this cmdlet
.NOTES
    General notes
.LINK
    https://api.itglue.com/developer/#ENDPOINT
.LINK
    https://github.com/itglue/powershellwrapper/...
#>