Updated examples and added more context

Author: sdwheeler

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

@@ -1,7 +1,7 @@
 ---
 description: Describes how to create and use a reference type variable. You can use reference type variables to permit a function to change the value of a variable that is passed to it.
 Locale: en-US
-ms.date: 08/24/2018
+ms.date: 12/12/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_ref?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about_Ref
@@ -10,18 +10,25 @@ title: about_Ref
 
 ## Short description
 
-Describes how to create and use a reference type variable. You can use
-reference type variables to permit a function to change the value
-of a variable that is passed to it.
+Describes how to create and use a reference type variable.
 
 ## Long description
 
-You can pass variables to functions _by reference_ or _by value_.
+You can pass variables to functions _by reference_ or _by value_. When you pass
+a variable _by value_, you are passing a copy of the data. When you pass a
+variable _by reference_, you are passing a reference to the original value.
+This allows the function to change the value of the variable that is passed to
+it.Reference types are created using `[ref]`, which is the type accelerator for
+the `[System.Management.Automation.PSReference]` type.
 
-When you pass a variable _by value_, you are passing a copy of the data.
+The primary purpose of `[ref]` is to enable passing PowerShell variables by
+reference to .NET method parameters marked as `ref`, `out`, or `in`. You can
+also define your own PowerShell function that take `[ref]` type parameters. In
+this usage, `[ref]` is applied to a _variable_, and the resulting `[ref]`
+instance can be used to indirectly modify that variable's value.
 
 In the following example, the function changes the value of the variable passed
-to it. In PowerShell, integers are value types so they are passed by value.
+to it. In PowerShell, integers are value types so they're passed by value.
 Therefore, the value of `$var` is unchanged outside the scope of the function.
 
 ```powershell
@@ -40,7 +47,7 @@ $var
 ```
 
 In the following example, a variable containing a `Hashtable` is passed to a
-function. `Hashtable` is an object type so by default it is passed to the
+function. `Hashtable` is an object type so by default it's passed to the
 function _by reference_.
 
 When passing a variable _by reference_, the function can change the data and
@@ -66,7 +73,7 @@ Test                           New Text
 The function adds a new key-value pair that persists outside of the function's
 scope.
 
-### Writing functions to accept reference parameters
+## Writing functions to accept reference parameters
 
 You can code your functions to take a parameter as a reference, regardless of
 the type of data passed. This requires that you specify the parameters type
@@ -98,7 +105,7 @@ $var
 3
 ```
 
-### Passing references to .NET methods
+## Passing references to .NET methods
 
 Some .NET methods may require you to pass a variable as a reference. When
 the method's definition uses the keywords `in`, `out`, or `ref` on a
@@ -126,7 +133,7 @@ PS> $number
 15
 ```
 
-### References and scopes
+## References and scopes
 
 References allow the value of a variable in the parent scope to be changed
 within a child scope.
@@ -148,59 +155,96 @@ $i = 0;$iRef = 1
 
 Only the reference type's variable was changed.
 
-### Relationship between [ref] and System.Management.Automation.PSReference
+## Using `[ref]` as a general-purpose object holder
 
-`Ref` is both a type accelerator for `System.Management.Automation.PSReference`
-(see [about_Type_Accelerators] for details) and a reserved keyword that
-PowerShell treats especially. Hence, `ref` and `PSReference` are not
-equivalents. The following script demonstrates their difference:
+You can also use `[ref]` as a general-purpose object holder. In this usage,
+`[ref]` is applied to a _value_ instead of a variable. Typically, the value is
+an instance of a _value type_, like a number. In most scenarios you can use a
+regular variable or parameter instead. However, this technique is useful in
+scenarios where passing an explicit value holder is undesired (for brevity) or
+not possible, such as in script-block parameter values.
+
+For example, you can use script-block parameter values to calculate the value
+of **NewName** parameter of the `Rename-Item` cmdlet. The `Rename-Item` cmdlet
+allows you to pipe items to it. The command run the script block passed to the
+**NewName** for each item in the pipeline. The script block run in a child
+scope. Modifying a variable in the caller's scope directly won't help and you
+can't pass arguments to the script block in this context.
+
+In this example, the script block passed to the **NewName** parameter
+increments the value of `$iRef` for each item in the pipeline. The script block
+creates a new name by adding a number to the beginning of the filename.
 
 ```powershell
-$x = 1
+$iRef = [ref] 0
+Get-ChildItem -File $setPath |
+    Rename-Item -NewName { '{0} - {1}' -f $iRef.Value++,$_.Name }
+```
 
-$a = [ref] $x
-$b = [System.Management.Automation.PSReference] $x
-$c = [ref] $x
+## Difference between `[ref]` and `[System.Management.Automation.PSReference]`
 
-$x +=4
-$a.Value +=3
-$b.Value +=2
-$c.Value +=1
+A reference type variable is created using
 
-$x, $a.Value, $b.Value, $c.Value | ForEach-Object {
-  Write-Output $PSItem
-}
-```
+Even though `[ref]` is a type accelerator for
+`[System.Management.Automation.PSReference]`, they behave differently.
+
+- When you use `[ref]` to cast a variable, PowerShell creates reference object
+  that contains reference to the original instance of the variable.
+- When you use `[System.Management.Automation.PSReference]` to cast a variable,
+  PowerShell creates reference object that contains a copy of the variable,
+  rather than a reference to the original instance.
 
-The output of this script is:
+For example, the following script creates a variable `$x` and two reference
+objects.
 
 ```powershell
-9
-9
-3
-9
+PS> $int = 1
+PS> $aRef = [ref] $int
+PS> $bRef = [System.Management.Automation.PSReference] $int
+PS> $int
+1
+PS> $aRef, $bRef
+
+Value
+-----
+    1
+    1
 ```
 
-The above script:
+At this point, both reference object have the same value as `$int`. By adding
+different values to the reference objects, we can see that `$aRef`, which was
+created using `[ref]`, is a reference to the original instance of `$int`.
+`$bRef` was created using `[System.Management.Automation.PSReference]` is a
+copy of the variable.
 
-- Creates an integer `$x` variable and assigns `1` to it.
-- Creates pointers `$a` and `$c` of `[ref]` types and points them at `$x`.
-- Creates pointer `$b` of `[PSReference]` type and points it, not at `$x`, but
-  a copy thereof, because PowerShell treats `[ref]` and `[PSReference]`
-  differently.
-- Adds 4 to `$x`, 3 to `$a`'s value, 2 to `$b`'s value, and 1 to `$a`'s value.
+```powershell
+PS> $aRef.Value+=2
+PS> $bRef.Value+=5
+PS> $int
+3
+PS> $aRef, $bRef
 
-In the script above, `$x`, `$a.Value`, and `$c.Value` point to the same memory
-location. They are the same, i.e., 1 + 4 + 3 + 1 = 9. But `$b.Value` refers to
-a copy of `$x` at the time of its creation. Hence, it contains 1 + 2 = 3.
+Value
+-----
+    3
+    6
+```
 
 ## See also
 
-- [about_Variables](about_Variables.md)
-- [about_Environment_Variables](about_Environment_Variables.md)
-- [about_Functions](about_Functions.md)
-- [about_Script_Blocks](about_Script_Blocks.md)
-- [about_Scopes](about_scopes.md)
-- [about_Type_accelerators]
-
-[about_Type_accelerators]: about_Type_Accelerators.md
+- [about_Variables][06]
+- [about_Environment_Variables][01]
+- [about_Functions][02]
+- [about_Script_Blocks][04]
+- [about_Scopes][03]
+- [about_Type_Accelerators][05]
+- [System.Management.Automation.PSReference][07]
+
+<!-- link references -->
+[01]: about_Environment_Variables.md
+[02]: about_Functions.md
+[03]: about_scopes.md
+[04]: about_Script_Blocks.md
+[05]: about_Type_Accelerators.md
+[06]: about_Variables.md
+[07]: xref:System.Management.Automation.PSReference