Update the help content for 'Push-OutputBinding'

build.ps1

@@ -37,6 +37,10 @@ if ($Bootstrap.IsPresent) {
         Write-Log -Warning "Module 'Pester' is missing. Installing 'Pester' ..."
         Install-Module -Name Pester -Scope CurrentUser -Force
     }
+    if (-not (Get-Module -Name platyPS -ListAvailable)) {
+        Write-Log -Warning "Module 'platyPS' is missing. Installing 'platyPS' ..."
+        Install-Module -Name platyPS -Scope CurrentUser -Force
+    }
 }
 
 # Clean step
@@ -95,4 +99,18 @@ if($Test.IsPresent) {
     if ($LASTEXITCODE -ne 0) { throw "xunit tests failed." }
 
     Invoke-Tests -Path "$PSScriptRoot/test/Unit/Modules" -OutputFile UnitTestsResults.xml
+
+    if (-not (Get-Module -Name platyPS -ListAvailable)) {
+        throw "Cannot find the 'platyPS' module. Please specify '-Bootstrap' to install build dependencies."
+    }
+    elseif (-not (Get-Command -Name git -CommandType Application)) {
+        throw "Cannot find 'git'. Please make sure it's in the 'PATH'."
+    }
+
+    # Cmdlet help docs should be up-to-date
+    Update-MarkdownHelp -Path ./docs/cmdlets
+    $diff = git diff ./docs/cmdlets
+    if ($diff) {
+        throw "Cmdlet help docs are not up-to-date, run Update-MarkdownHelp.`n$diff`n"
+    }
 }

docs/cmdlets/Get-OutputBinding.md

@@ -0,0 +1,88 @@
+---
+external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
+Module Name: Microsoft.Azure.Functions.PowerShellWorker
+online version:
+schema: 2.0.0
+---
+
+# Get-OutputBinding
+
+## SYNOPSIS
+Gets the hashtable of the output bindings set so far.
+
+## SYNTAX
+
+```
+Get-OutputBinding [[-Name] <String[]>] [-Purge] [<CommonParameters>]
+```
+
+## DESCRIPTION
+Gets the hashtable of the output bindings set so far.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```
+Get-OutputBinding
+```
+
+Gets the hashtable of all the output bindings set so far.
+
+### EXAMPLE 2
+```
+Get-OutputBinding -Name res
+```
+
+Gets the hashtable of specific output binding.
+
+### EXAMPLE 3
+```
+Get-OutputBinding -Name r*
+```
+
+Gets the hashtable of output bindings that match the wildcard.
+
+## PARAMETERS
+
+### -Name
+The name of the output binding you want to get.
+Supports wildcards.
+
+```yaml
+Type: String[]
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 1
+Default value: *
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -Purge
+Clear all stored output binding values.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+### The hashtable of binding names to their respective value.
+## NOTES
+
+## RELATED LINKS

docs/cmdlets/Push-OutputBinding.md

@@ -0,0 +1,149 @@
+---
+external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
+Module Name: Microsoft.Azure.Functions.PowerShellWorker
+online version:
+schema: 2.0.0
+---
+
+# 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.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```
+Push-OutputBinding -Name response -Value "output #1"
+```
+
+The output binding of "response" will have the value of "output #1"
+
+### EXAMPLE 2
+```
+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
+```
+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
+```
+Push-OutputBinding -Name outQueue -Value "output #1"
+```
+
+The output binding of "outQueue" will have the value of "output #1"
+
+### EXAMPLE 5
+```
+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
+```
+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".
+
+## PARAMETERS
+
+### -Name
+The name of the output binding you want to set.
+
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Value
+The value of the output binding you want to set.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 2
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -Clobber
+(Optional) If specified, will force the value to be set for a specified output binding.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

docs/cmdlets/Trace-PipelineObject.md

@@ -0,0 +1,58 @@
+---
+external help file: Microsoft.Azure.Functions.PowerShellWorker-help.xml
+Module Name: Microsoft.Azure.Functions.PowerShellWorker
+online version:
+schema: 2.0.0
+---
+
+# Trace-PipelineObject
+
+## SYNOPSIS
+Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline.
+
+## SYNTAX
+
+```
+Trace-PipelineObject [-InputObject] <Object> [<CommonParameters>]
+```
+
+## DESCRIPTION
+INTERNAL POWERSHELL WORKER USE ONLY.
+Writes the formatted output of the pipeline object to the information stream before passing the object down to the pipeline.
+
+## EXAMPLES
+
+### Example 1
+```powershell
+PS C:\> {{ Add example code here }}
+```
+
+{{ Add example description here }}
+
+## PARAMETERS
+
+### -InputObject
+The object from pipeline.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

src/Modules/Microsoft.Azure.Functions.PowerShellWorker/Microsoft.Azure.Functions.PowerShellWorker.psm1

@@ -40,6 +40,8 @@ enum DataCollectingBehavior {
     Gets the hashtable of output bindings that match the wildcard.
 .PARAMETER Name
     The name of the output binding you want to get. Supports wildcards.
+.PARAMETER Purge
+    Clear all stored output binding values.
 .OUTPUTS
     The hashtable of binding names to their respective value.
 #>
@@ -202,17 +204,55 @@ function Merge-Collection
 .SYNOPSIS
     Sets the value for the specified output binding.
 .DESCRIPTION
-    Sets the value for the specified output binding.
+    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.
 .EXAMPLE
-    PS > Push-OutputBinding -Name res -Value "my output"
-    The output binding of "res" will have the value of "my output"
+    PS > Push-OutputBinding -Name response -Value "output #1"
+    The output binding of "response" will have the value of "output #1"
+.EXAMPLE
+    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
+    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
+    PS > Push-OutputBinding -Name outQueue -Value "output #1"
+    The output binding of "outQueue" will have the value of "output #1"
+.EXAMPLE
+    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
+    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".
 .PARAMETER Name
     The name of the output binding you want to set.
 .PARAMETER Value
     The value of the output binding you want to set.
-.PARAMETER InputObject
-    The hashtable that contains the output binding names to their respective value.
-.PARAMETER Force
+.PARAMETER Clobber
     (Optional) If specified, will force the value to be set for a specified output binding.
 #>
 function Push-OutputBinding