Fixes #3014 - Clarify delay bind script blocks (#4285)

* Fixes #3014 - Clarify delay bind script blocks

* Editorial review

reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -250,16 +250,6 @@ Param(
 )
 ```
 
-> [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically during
-> ParameterBinding. The result is bound to the parameter. Delay binding
-> does **not** work for parameters defined as type `System.Object`, the
-> script block is passed through **without** being invoked.
->
-> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
-
 ### ValueFromPipelineByPropertyName Argument
 
 The `ValueFromPipelineByPropertyName` argument indicates that the parameter
@@ -283,6 +273,18 @@ Param(
 )
 ```
 
+> [!NOTE]
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+>
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
+
 ### ValueFromRemainingArguments Argument
 
 The `ValueFromRemainingArguments` argument indicates that the parameter

reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md

@@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value
 has a property called **Name**.
 
 > [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically
-> during ParameterBinding. The result is bound to the parameter. Delay
-> binding does **not** work for parameters defined as type `System.Object`,
-> the script block is passed through **without** being invoked.
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
 >
-> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md).
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
 
 #### Accepts Wildcard Characters
 

reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md

@@ -138,25 +138,49 @@ For more information about the call operator, see [about_Operators](about_Operat
 
 ## Using delay-bind script blocks with parameters
 
-A **delay-bind** script block allows you to pipe input to a given parameter,
-then use script blocks for other parameters using the pipeline variable `$_` to
-reference the same object.
+A typed parameter that accepts pipeline input (`by Value`) or
+(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+Within the **delay-bind** script block, you can reference the piped in object
+using the pipeline variable `$_`.
 
 ```powershell
 # Renames config.log to old_config.log
 dir config.log | Rename-Item -NewName {"old_" + $_.Name}
 ```
 
-The additional parameters must accept pipeline input
-(`by Value`) or (`by PropertyName`).
-
 In more complex cmdlets, delay-bind script blocks allow the reuse of one piped
 in object to populate other parameters.
 
+Notes on **delay-bind** script blocks as parameters:
+
+- You must explicitly specify any parameter names you use with **delay-bind**
+  script blocks.
+- The parameter must not be untyped, and the parameter's type cannot be
+  `[scriptblock]` or `[object]`.
+- You receive an error if you use a **delay-bind** script block without
+  providing pipeline input.
+
+  ```powershell
+  Rename-Item -NewName {$_.Name + ".old"}
+  ```
+
+  ```Output
+  Rename-Item : Cannot evaluate parameter 'NewName' because its argument is
+  specified as a script block and there is no input. A script block cannot
+  be evaluated without input.
+  At line:1 char:23
+  +  Rename-Item -NewName {$_.Name + ".old"}
+  +                       ~~~~~~~~~~~~~~~~~~
+      + CategoryInfo          : MetadataError: (:) [Rename-Item],
+        ParameterBindingException
+      + FullyQualifiedErrorId : ScriptBlockArgumentNoInput,
+        Microsoft.PowerShell.Commands.RenameItemCommand
+  ```
+
 ## See Also
 
 [about_Functions](about_Functions.md)
 
 [about_Functions_Advanced](about_Functions_Advanced.md)
 
-[about_Operators](about_Operators.md)
+[about_Operators](about_Operators.md)

reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -250,16 +250,6 @@ Param(
 )
 ```
 
-> [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically during
-> ParameterBinding. The result is bound to the parameter. Delay binding
-> does **not** work for parameters defined as type `System.Object`, the
-> script block is passed through **without** being invoked.
->
-> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
-
 ### ValueFromPipelineByPropertyName Argument
 
 The `ValueFromPipelineByPropertyName` argument indicates that the parameter
@@ -283,6 +273,18 @@ Param(
 )
 ```
 
+> [!NOTE]
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+>
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
+
 ### ValueFromRemainingArguments Argument
 
 The `ValueFromRemainingArguments` argument indicates that the parameter

reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md

@@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value
 has a property called **Name**.
 
 > [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically
-> during ParameterBinding. The result is bound to the parameter. Delay
-> binding does **not** work for parameters defined as type `System.Object`,
-> the script block is passed through **without** being invoked.
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
 >
-> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md).
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
 
 #### Accepts Wildcard Characters
 

reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md

@@ -8,7 +8,6 @@ title:  about_Script_Blocks
 # About Script Blocks
 
 ## Short description
-
 Defines what a script block is and explains how to use script blocks in
 the PowerShell programming language.
 
@@ -138,25 +137,49 @@ For more information about the call operator, see [about_Operators](about_Operat
 
 ## Using delay-bind script blocks with parameters
 
-A **delay-bind** script block allows you to pipe input to a given parameter,
-then use script blocks for other parameters using the pipeline variable `$_` to
-reference the same object.
+A typed parameter that accepts pipeline input (`by Value`) or
+(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+Within the **delay-bind** script block, you can reference the piped in object
+using the pipeline variable `$_`.
 
 ```powershell
 # Renames config.log to old_config.log
 dir config.log | Rename-Item -NewName {"old_" + $_.Name}
 ```
 
-The additional parameters must accept pipeline input
-(`by Value`) or (`by PropertyName`).
-
 In more complex cmdlets, delay-bind script blocks allow the reuse of one piped
 in object to populate other parameters.
 
+Notes on **delay-bind** script blocks as parameters:
+
+- You must explicitly specify any parameter names you use with **delay-bind**
+  script blocks.
+- The parameter must not be untyped, and the parameter's type cannot be
+  `[scriptblock]` or `[object]`.
+- You receive an error if you use a **delay-bind** script block without
+  providing pipeline input.
+
+  ```powershell
+  Rename-Item -NewName {$_.Name + ".old"}
+  ```
+
+  ```Output
+  Rename-Item : Cannot evaluate parameter 'NewName' because its argument is
+  specified as a script block and there is no input. A script block cannot
+  be evaluated without input.
+  At line:1 char:23
+  +  Rename-Item -NewName {$_.Name + ".old"}
+  +                       ~~~~~~~~~~~~~~~~~~
+      + CategoryInfo          : MetadataError: (:) [Rename-Item],
+        ParameterBindingException
+      + FullyQualifiedErrorId : ScriptBlockArgumentNoInput,
+        Microsoft.PowerShell.Commands.RenameItemCommand
+  ```
+
 ## See Also
 
 [about_Functions](about_Functions.md)
 
 [about_Functions_Advanced](about_Functions_Advanced.md)
 
-[about_Operators](about_Operators.md)
+[about_Operators](about_Operators.md)

reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -249,16 +249,6 @@ Param(
 )
 ```
 
-> [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically during
-> ParameterBinding. The result is bound to the parameter. Delay binding
-> does **not** work for parameters defined as type `System.Object`, the
-> script block is passed through **without** being invoked.
->
-> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
-
 ### ValueFromPipelineByPropertyName Argument
 
 The `ValueFromPipelineByPropertyName` argument indicates that the parameter
@@ -282,6 +272,18 @@ Param(
 )
 ```
 
+> [!NOTE]
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+>
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
+
 ### ValueFromRemainingArguments Argument
 
 The `ValueFromRemainingArguments` argument indicates that the parameter

reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md

@@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value
 has a property called **Name**.
 
 > [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically
-> during ParameterBinding. The result is bound to the parameter. Delay
-> binding does **not** work for parameters defined as type `System.Object`,
-> the script block is passed through **without** being invoked.
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
 >
-> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md).
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
 
 #### Accepts Wildcard Characters
 

reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md

@@ -137,21 +137,45 @@ For more information about the call operator, see [about_Operators](about_Operat
 
 ## Using delay-bind script blocks with parameters
 
-A **delay-bind** script block allows you to pipe input to a given parameter,
-then use script blocks for other parameters using the pipeline variable `$_` to
-reference the same object.
+A typed parameter that accepts pipeline input (`by Value`) or
+(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+Within the **delay-bind** script block, you can reference the piped in object
+using the pipeline variable `$_`.
 
 ```powershell
 # Renames config.log to old_config.log
 dir config.log | Rename-Item -NewName {"old_" + $_.Name}
 ```
 
-The additional parameters must accept pipeline input
-(`by Value`) or (`by PropertyName`).
-
 In more complex cmdlets, delay-bind script blocks allow the reuse of one piped
 in object to populate other parameters.
 
+Notes on **delay-bind** script blocks as parameters:
+
+- You must explicitly specify any parameter names you use with **delay-bind**
+  script blocks.
+- The parameter must not be untyped, and the parameter's type cannot be
+  `[scriptblock]` or `[object]`.
+- You receive an error if you use a **delay-bind** script block without
+  providing pipeline input.
+
+  ```powershell
+  Rename-Item -NewName {$_.Name + ".old"}
+  ```
+
+  ```Output
+  Rename-Item : Cannot evaluate parameter 'NewName' because its argument is
+  specified as a script block and there is no input. A script block cannot
+  be evaluated without input.
+  At line:1 char:23
+  +  Rename-Item -NewName {$_.Name + ".old"}
+  +                       ~~~~~~~~~~~~~~~~~~
+      + CategoryInfo          : MetadataError: (:) [Rename-Item],
+        ParameterBindingException
+      + FullyQualifiedErrorId : ScriptBlockArgumentNoInput,
+        Microsoft.PowerShell.Commands.RenameItemCommand
+  ```
+
 ## See Also
 
 [about_Functions](about_Functions.md)

reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md

@@ -250,16 +250,6 @@ Param(
 )
 ```
 
-> [!NOTE]
-> A parameter that accepts pipeline input (`by Value`) will enable use of
-> **delay-bind** script blocks on all other parameters defined to accept
-> pipeline input. The **delay-bind** script block is run automatically during
-> ParameterBinding. The result is bound to the parameter. Delay binding
-> does **not** work for parameters defined as type `System.Object`, the
-> script block is passed through **without** being invoked.
->
-> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
-
 ### ValueFromPipelineByPropertyName Argument
 
 The `ValueFromPipelineByPropertyName` argument indicates that the parameter
@@ -283,6 +273,18 @@ Param(
 )
 ```
 
+> [!NOTE]
+> A typed parameter that accepts pipeline input (`by Value`) or
+> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter.
+>
+> The **delay-bind** script block is run automatically during
+> **ParameterBinding**. The result is bound to the parameter. Delay binding
+> does **not** work for parameters defined as type `ScriptBlock` or
+> `System.Object`, the script block is passed through
+> **without** being invoked.
+>
+> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md)
+
 ### ValueFromRemainingArguments Argument
 
 The `ValueFromRemainingArguments` argument indicates that the parameter