Fixes #3290, Fixes #3285 Rewrite topics to explain automatic collecti…

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

@@ -29,7 +29,10 @@ positional, switch, or dynamic parameters. Function parameters can be read
 from the command line or from the pipeline.
 
 Functions can return values that can be displayed, assigned to variables, or
-passed to other functions or cmdlets.
+passed to other functions or cmdlets. You can also specify a return value using
+the `return` keyword. The `return` keyword does not affect or suppress other
+output returned from your function. However, the `return` keyword exits the
+function at that line. For more information, see [about_Return](about_Return.md).
 
 The function's statement list can contain different types of statement lists
 with the keywords `Begin`, `Process`, and `End`. These statement lists

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

@@ -7,73 +7,83 @@ title:  about_Return
 ---
 # About Return
 
-## SHORT DESCRIPTION
+## Short description
 
 Exits the current scope, which can be a function, script, or script block.
 
-## LONG DESCRIPTION
+## Long description
 
- The Return keyword exits a function, script, or script block. It can be used
- to exit a scope at a specific point, to return a value, or to indicate that
- the end of the scope has been reached.
+The `return` keyword exits a function, script, or script block. It can be used
+to exit a scope at a specific point, to return a value, or to indicate that the
+end of the scope has been reached.
 
 Users who are familiar with languages like C or C\# might want to use the
-Return keyword to make the logic of leaving a scope explicit.
+`return` keyword to make the logic of leaving a scope explicit.
 
-In PowerShell, the results of each statement are returned as output,
-even without a statement that contains the Return keyword. Languages like C or
-C\# return only the value or values that are specified by the Return keyword.
+In PowerShell, the results of each statement are returned as output, even
+without a statement that contains the Return keyword. Languages like C or C\#
+return only the value or values that are specified by the `return` keyword.
 
-### SYNTAX
+### Syntax
 
-The syntax for the Return keyword is as follows:
+The syntax for the `return` keyword is as follows:
 
 ```
 return [<expression>]
 ```
 
-The Return keyword can appear alone, or it can be followed by a value or
+The `return` keyword can appear alone, or it can be followed by a value or
 expression, as follows:
 
-```
+```powershell
 return
 return $a
 return (2 + $a)
 ```
 
+### Examples
 
-### EXAMPLES
+The following example uses the `return` keyword to exit a function at a
+specific point if a conditional is met. Odd numbers are not multiplied
+because the return statement exits before that statement can execute.
 
-The following example uses the Return keyword to exit a function at a specific
-point if a conditional is met:
-
-```
-function ScreenPassword($instance)
+```powershell
+function MultiplyEven
 {
-    if (!($instance.screensaversecure)) {return $instance.name}
-    <additional statements>
+    param($number)
+
+    if ($number % 2) { return "$number is not even" }
+    $number * 2
 }
 
-foreach ($a in @(get-wmiobject win32_desktop)) { ScreenPassword($a) }
+1..10 | ForEach-Object {MultiplyEven -Number $_}
 ```
 
-This script checks each user account. The ScreenPassword function returns the
-name of any user account that does not have a password-protected screen saver.
-If the screen saver is password protected, the function completes any other
-statements to be run, and PowerShell does not return any value.
+```output
+1 is not even
+4
+3 is not even
+8
+5 is not even
+12
+7 is not even
+16
+9 is not even
+20
+```
 
-In PowerShell, values can be returned even if the Return keyword is not used.
+In PowerShell, values can be returned even if the `return` keyword is not used.
 The results of each statement are returned. For example, the following
-statements return the value of the \$a variable:
+statements return the value of the `$a` variable:
 
-```
+```powershell
 $a
 return
 ```
 
-The following statement also returns the value of $a:
+The following statement also returns the value of `$a`:
 
-```
+```powershell
 return $a
 ```
 
@@ -88,33 +98,109 @@ function calculation {
     $value += 73
     return $value
 }
-```
-
-Running this function and assigning the result to a variable has the following
-effect:
 
-```powershell
 $a = calculation 14
 ```
 
 The "Please wait. Working on calculation..." string is not displayed. Instead,
-it is assigned to the $a variable, as in the following example:
+it is assigned to the `$a` variable, as in the following example:
 
-```output
+```
 PS> $a
 Please wait. Working on calculation...
 87
 ```
 
 Both the informational string and the result of the calculation are returned
-by the function and assigned to the \$a variable.
+by the function and assigned to the `$a` variable.
+
+### Return values and the Pipeline
+
+When you return a collection from your script block or function, PowerShell
+automatically unrolls the members and passes them one at a time through the
+pipeline. This is due to PowerShell's one-at-a-time processing. For more
+information, see [about_pipelines](about_pipelines.md).
+
+This concept is illustrated by the following sample function that returns an
+array of numbers. The output from the function is piped to the `Measure-Object`
+cmdlet which counts the number of objects in the pipeline.
+
+```powershell
+function Test-Return
+{
+    $array = 1,2,3
+    return $array
+}
+Test-Return | Measure-Object
+```
+
+```Output
+Count    : 3
+Average  :
+Sum      :
+Maximum  :
+Minimum  :
+Property :
+```
 
-## SEE ALSO
+To force a script block or function to return collection as a single
+object to the pipeline, use one of the following two methods:
+
+- Unary array expression
+
+  Utilizing a unary expression you can send your return value down the pipeline
+  as a single object as illustrated by the following example.
+
+  ```powershell
+  function Test-Return
+  {
+      $array = 1,2,3
+      return (, $array)
+  }
+  Test-Return | Measure-Object
+  ```
+
+  ```Output
+  Count    : 1
+  Average  :
+  Sum      :
+  Maximum  :
+  Minimum  :
+  Property :
+  ```
+
+- `Write-Output` with **NoEnumerate** parameter.
+
+  You can also use the `Write-Output` cmdlet with the **NoEnumerate**
+  parameter. The example below uses the `Measure-Object` cmdlet to count the
+  objects sent to the pipeline from the sample function by the `return`
+  keyword.
+
+  ```powershell
+  function Test-Return
+  {
+      $array = 1, 2, 3
+      return Write-Output -NoEnumerate $array
+  }
+
+  Test-Return | Measure-Object
+  ```
+
+  ```Output
+  Count    : 1
+  Average  :
+  Sum      :
+  Maximum  :
+  Minimum  :
+  Property :
+  ```
+
+## See also
 
 [about_Language_Keywords](about_Language_Keywords.md)
 
 [about_Functions](about_Functions.md)
 
 [about_Scopes](about_Scopes.md)
 
-[about_Script_Blocks](about_Script_Blocks.md)
+[about_Script_Blocks](about_Script_Blocks.md)

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

@@ -28,6 +28,11 @@ the following syntax:
 A script block returns the output of all the commands in the script block,
 either as a single object or as an array.
 
+You can also specify a return value using the `return` keyword. The `return`
+keyword does not affect or suppress other output returned from your script
+block. However, the `return` keyword exits the script block at that line. For
+more information, see [about_Return](about_Return.md).
+
 Like functions, a script block can include parameters. Use the Param
 keyword to assign named parameters, as shown in the following syntax: