Update the help content for 'Push-OutputBinding'

[daxian-dbw]

Update the help content for Push-OutputBinding. Get-Help looks as follows after the update:

PS:55> Get-Help Push-OutputBinding -Full

NAME
    Push-OutputBinding

SYNOPSIS
    Sets the value for the specified output binding.


SYNTAX
    Push-OutputBinding [-Name] <String> [-Value] <Object> [-Clobber] [<CommonParameters>]


DESCRIPTION
    When running in the Functions runtime, this cmdlet is aware of the output bindings
    defined for the function that is invoking this cmdlet. Hence, it's able to decide
    whether an output binding accepts singleton value only or a collection of values.

    For example, the HTTP output binding only accepts one response object, while the
    queue output binding can accept one or multiple queue messages.

    With this knowledge, the 'Push-OutputBinding' cmdlet acts differently based on the
    value specified for '-Name':

    - If the specified name cannot be resolved to a valid output binding, then an error
      will be thrown;

    - If the output binding corresponding to that name accepts a collection of values,
      then it's allowed to call 'Push-OutputBinding' with the same name repeatedly in
      the function script to push multiple values;

    - If the output binding corresponding to that name only accepts a singleton value,
      then the second time calling 'Push-OutputBinding' with that name will result in
      an error, with detailed message about why it failed.


PARAMETERS
    -Name <String>
        The name of the output binding you want to set.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Value <Object>
        The value of the output binding you want to set.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?       true (ByValue)
        Accept wildcard characters?  false

    -Clobber [<SwitchParameter>]
        (Optional) If specified, will force the value to be set for a specified output binding.

        Required?                    false
        Position?                    named
        Default value                False
        Accept pipeline input?       false
        Accept wildcard characters?  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

OUTPUTS

    -------------------------- EXAMPLE 1 --------------------------

    PS >Push-OutputBinding -Name response -Value "output #1"

    The output binding of "response" will have the value of "output #1"




    -------------------------- EXAMPLE 2 --------------------------

    PS >Push-OutputBinding -Name response -Value "output #2"

    The output binding is 'http', which accepts a singleton value only.
    So an error will be thrown from this second run.




    -------------------------- EXAMPLE 3 --------------------------

    PS >Push-OutputBinding -Name response -Value "output #3" -Clobber

    The output binding is 'http', which accepts a singleton value only.
    But you can use '-Clobber' to override the old value.
    The output binding of "response" will now have the value of "output #3"




    -------------------------- EXAMPLE 4 --------------------------

    PS >Push-OutputBinding -Name outQueue -Value "output #1"

    The output binding of "outQueue" will have the value of "output #1"




    -------------------------- EXAMPLE 5 --------------------------

    PS >Push-OutputBinding -Name outQueue -Value "output #2"

    The output binding is 'queue', which accepts multiple output values.
    The output binding of "outQueue" will now have a list with 2 items: "output #1", "output #2"




    -------------------------- EXAMPLE 6 --------------------------

    PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

    When the value is a collection, the collection will be unrolled and elements of the collection
    will be added to the list. The output binding of "outQueue" will now have a list with 4 items:
    "output #1", "output #2", "output #3", "output #4".

[TylerLeonhardt]

Do you want to also generate the markdown docs a with PlatyPS and store them in the repo?

[daxian-dbw]

Good point. Let me create a docs folder and put the help markdown there.

[TylerLeonhardt]

should we include PlatyPS docgen in the build script then?

[daxian-dbw]

should we include PlatyPS docgen in the build script then?

Why? Do you want to generate those markdown files during every build but not checking them in the repo?
Checking them in the repo allows people to read the help docs directly in the GitHub page.

[TylerLeonhardt]

It's more about helping us make sure our docs are always updated. But a CI check would also work for me like this one :)

The ideal situation is making sure every parameter has docs, but I'm fine calling that out of scope if you want

[daxian-dbw]

Thanks for clarifying, I get your point now.

A check like that would be useful when we only have script cmdlet. I will add the check.
However, once we have C# cmdlets (for durable functions), we will have to manually update the help markdown files like what we do in PowerShell-Docs. By that time, the markdown update check would result in false positive errors for the C# cmdlets. We probably will need to white-list the C# cmdlets at that time.

[TylerLeonhardt]

this is false but it does support wildcard characters?

[daxian-dbw]

A bug in PlatyPS? I don't think it's able to figure out if a parameter accepts wildcard.

[daxian-dbw]

Cannot change it manually, unless we revert the doc check code in build.

[TylerLeonhardt]

LGTM only one question about the platyPS output