Apply suggestions Mikey

Author: Gijsreyn

docs/reference/schemas/config/functions/shallowMerge.md

@@ -19,25 +19,30 @@ shallowMerge(<inputArray>)
 
 The `shallowMerge()` function takes an array of objects and combines them into a single
 object by merging their properties. When the same property name appears in multiple objects,
-the value from the last object in the array takes precedence.
+the value from the last object in the array with that property takes precedence.
 
-This is a **shallow merge**, meaning:
+This is a _shallow merge_, which applies the following rules:
 
-- Top-level properties are merged from all objects
-- If a property value is an object, it replaces the entire object from previous objects
-  rather than merging the nested properties
-- Arrays and other complex types are also replaced entirely, not combined
+- The first object in the array defines the base value for the merged object.  
+- The function processes each object in the array in the order they're defined.  
+- When processing each object, the function iterates over every top-level property defined for that  
+  object and:  
+
+  - If the merged object doesn't already have the property, the function adds that property to the  
+    merged object with the value from the current object.  
+  - If the merged object does have the property, the function _replaces_ the existing value with  
+    the value from the current object, even when the value is an object or array.  
 
 This function is useful for:
 
-- Building composite configuration objects from multiple sources
-- Applying configuration overrides where later values take precedence
-- Combining default settings with user-specified customizations
-- Merging environment-specific configurations
+- Building composite configuration objects from multiple sources.  
+- Applying configuration overrides where later values take precedence.  
+- Combining default settings with user-specified customizations.  
+- Merging environment-specific configurations.
 
-The shallow merge behavior differs from a deep merge (like [`union()`][00]) where nested
-objects would be recursively merged. With `shallowMerge()`, nested structures are replaced
-entirely by the last object's value.
+The shallow merge behavior differs from a deep merge (like [`union()`][00]) where nested  
+objects are recursively merged. The `shallowMerge()` function replaces nested structures  
+entirely with the value defined by the last object with that property in the input array.
 
 ## Examples
 
@@ -53,7 +58,13 @@ resources:
 - name: Echo
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[shallowMerge(createArray(createObject('host', 'localhost', 'port', 8080), createObject('port', 9000, 'ssl', true())))]"
+    output: >-  
+      [shallowMerge(  
+        createArray(  
+          createObject('host', 'localhost', 'port', 8080),  
+          createObject('port', 9000, 'ssl', true())  
+        )  
+      )]
 ```
 
 ```bash
@@ -74,9 +85,8 @@ messages: []
 hadErrors: false
 ```
 
-Notice how the `port` value from the second object (9000) replaces the value from the first
-object (8080), while properties that only exist in one object (`host` and `ssl`) are
-preserved.
+In this example, the `port` value from the second object (`9000`) replaces the value from the first  
+object (`8080`), while properties that only exist in one object (`host` and `ssl`) are preserved.
 
 ### Example 2 - Apply multiple configuration layers
 
@@ -105,7 +115,14 @@ resources:
 - name: Echo
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[shallowMerge(createArray(parameters('defaults'), parameters('environment'), parameters('userPrefs')))]"
+    output: >-  
+      [shallowMerge(  
+        createArray(  
+          parameters('defaults'),  
+          parameters('environment'),  
+          parameters('userPrefs')  
+        )  
+      )]
 ```
 
 ```bash
@@ -141,7 +158,19 @@ resources:
 - name: Echo
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[shallowMerge(createArray(createObject('database', createObject('host', 'localhost', 'port', 5432, 'ssl', true())), createObject('database', createObject('host', 'prod.db.local'))))]"
+    output: >-  
+      [shallowMerge(  
+        createArray(  
+          createObject(  
+            'database',  
+            createObject('host', 'localhost', 'port', 5432, 'ssl', true())  
+          ),  
+          createObject(  
+            'database',  
+            createObject('host', 'prod.db.local')  
+          )  
+        )  
+      )]
 ```
 
 ```bash
@@ -175,7 +204,14 @@ resources:
 - name: Echo
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[shallowMerge(createArray(createObject('name', 'Service1', 'enabled', true()), createObject(), createObject('version', '2.0')))]"
+    output: >-  
+      [shallowMerge(  
+        createArray(  
+          createObject('name', 'Service1', 'enabled', true()),  
+          createObject(),  
+          createObject('version', '2.0')  
+        )  
+      )]
 ```
 
 ```bash
@@ -210,7 +246,13 @@ resources:
 - name: Echo
   type: Microsoft.DSC.Debug/Echo
   properties:
-    output: "[shallowMerge(createArray(createObject('newUI', false(), 'darkMode', true(), 'beta', false()), createObject('newUI', true()), createObject('beta', true())))]"
+    output: >-  
+      [shallowMerge(  
+        createArray(  
+          createObject('newUI', false(), 'darkMode', true(), 'beta', false()),  
+          createObject('newUI', true()), createObject('beta', true())  
+        )  
+      )]
 ```
 
 ```bash
@@ -302,9 +344,34 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      merged: "[shallowMerge(createArray(parameters('baseConfig'), parameters('overrides')))]"
-      keys: "[objectKeys(shallowMerge(createArray(parameters('baseConfig'), parameters('overrides'))))]"
-      hasRetries: "[contains(objectKeys(shallowMerge(createArray(parameters('baseConfig'), parameters('overrides')))), 'retries')]"
+      merged: >-  
+        [shallowMerge(  
+          createArray(  
+            parameters('baseConfig'),  
+            parameters('overrides')  
+          )  
+        )]  
+      keys: >-  
+        [objectKeys(  
+          shallowMerge(  
+            createArray(  
+              parameters('baseConfig'),  
+              parameters('overrides')  
+            )  
+          )  
+        )]  
+      hasRetries: >-  
+        [contains(  
+          objectKeys(  
+            shallowMerge(  
+              createArray(  
+                parameters('baseConfig'),  
+                parameters('overrides')  
+              )  
+            )  
+          ),  
+          'retries'  
+        )]
 ```
 
 ```bash
@@ -381,8 +448,9 @@ Position: 1
 
 ## Output
 
-Returns a single object containing all properties from the input objects. When the same
-property appears in multiple objects, the value from the last object in the array is used.
+Returns a single object containing all properties from the input objects. When the same property  
+appears in multiple objects, the value from the last object in the array with that property is  
+retained, replacing all prior values for the property.
 
 ```yaml
 Type: object
@@ -396,13 +464,15 @@ The function will return an error in the following cases:
 
 ## Notes
 
-- This is a **shallow merge** - nested objects are replaced, not merged recursively
-- Properties from objects later in the array override properties from earlier objects
-- Empty objects in the array don't affect the merge
-- Non-object elements in the array are ignored
-- An empty array returns an empty object
-- The function processes objects in array order, so the last object has highest precedence
-- For recursive/deep merging of nested objects, consider using [`union()`][00] instead
+- This function performs a _shallow merge_ - the function replaces nested objects, it doesn't merge
+  them recursively.  
+- The function replaces the value for properties defined by earlier objects in the input array with  
+  the value from objects later in the array.  
+- The function ignores empty objects in the input array.  
+- The function ignores non-object elements in the input array.  
+- The function returns an empty object when the input is an empty array.  
+- The function processes objects in array order, so the last object has highest precedence  
+- For recursive/deep merging of nested objects, consider using [`union()`][00] instead.
 
 ## Related functions
 

docs/reference/schemas/config/functions/tryWhich.md

@@ -7,7 +7,8 @@ title:       tryWhich
 
 ## Synopsis
 
-Attempts to locate an executable in the system PATH and returns its full path, or null if not found.
+Looks for an executable in the `PATH` environment variable and returns the full path to that  
+executable or null if not found.
 
 ## Syntax
 
@@ -17,20 +18,20 @@ tryWhich(<commandName>)
 
 ## Description
 
-The `tryWhich()` function searches for an executable in the system's PATH environment variable
-and returns the full path to the executable if found. If the executable is not found, the
-function returns `null` instead of generating an error.
+The `tryWhich()` function searches for an executable in the `PATH` environment variable and returns  
+the full path to the executable if found. If the executable isn't discoverable, the function  
+returns `null` instead of generating an error.
 
 This function is useful for:
 
-- Checking if a required command-line tool is available before using it
-- Conditionally configuring resources based on available system tools
-- Validating prerequisites in configurations
-- Finding the exact path to executables for use in scripts or commands
+- Checking whether a required command-line tool is available before invoking it.  
+- Conditionally configuring resources based on available system tools.  
+- Validating prerequisites in configurations.  
+- Finding the exact path to executables for use in scripts or commands.
 
-The function searches the PATH in the same way the operating system would when executing a
-command. On Windows, it automatically checks for common executable extensions (.exe, .cmd,
-.bat, etc.).
+The function searches the `PATH` in the same way the operating system would when executing a  
+command. On Windows, it automatically checks for common executable extensions, like `.exe`, `.cmd`,  
+and `.bat`, if no extension is provided.
 
 Unlike a strict path lookup that would fail if the executable is missing, `tryWhich()`
 gracefully returns `null`, making it ideal for conditional logic with [`if()`][00] or
@@ -52,7 +53,12 @@ resources:
   properties:
     output:
       gitPath: "[tryWhich('git')]"
-      hasGit: "[if(equals(tryWhich('git'), null()), false(), true())]"
+      hasGit: >-  
+        [if(  
+          equals(tryWhich('git'), null()),  
+          false(),  
+          true()  
+        )]
 ```
 
 ```bash
@@ -72,7 +78,8 @@ messages: []
 hadErrors: false
 ```
 
-If `git` is not installed, `gitPath` would be `null` and `hasGit` would be `false`.
+If `git` wasn't discoverable in the `PATH` environmental variable, `gitPath` would be `null` and `hasGit`
+would be `false`.
 
 ### Example 2 - Provide fallback paths with coalesce
 
@@ -87,7 +94,12 @@ resources:
   type: Microsoft.DSC.Debug/Echo
   properties:
     output:
-      pythonPath: "[coalesce(tryWhich('python3'), tryWhich('python'), '/usr/bin/python')]"
+      pythonPath: >-  
+        [coalesce(  
+          tryWhich('python3'),  
+          tryWhich('python'),  
+          '/usr/bin/python'  
+        )]
 ```
 
 ```bash
@@ -106,8 +118,9 @@ messages: []
 hadErrors: false
 ```
 
-This tries `python3` first, falls back to `python`, and finally uses a default path if
-neither is found in PATH.
+In this example, the function first looks for `python3` in the `PATH` environmental variable. If  
+that executable isn't discovered, it then looks for `python`. If neither executable is discovered,  
+it falls back to the specified default value, `/usr/bin/python3`.
 
 ### Example 3 - Validate multiple prerequisites
 
@@ -126,7 +139,12 @@ resources:
         docker: "[tryWhich('docker')]"
         kubectl: "[tryWhich('kubectl')]"
         helm: "[tryWhich('helm')]"
-      allFound: "[and(not(equals(tryWhich('docker'), null())), not(equals(tryWhich('kubectl'), null())), not(equals(tryWhich('helm'), null())))]"
+      allFound: >-  
+        [and(  
+          not(equals(tryWhich('docker'), null())),  
+          not(equals(tryWhich('kubectl'), null())),  
+          not(equals(tryWhich('helm'), null()))  
+        )]
 ```
 
 ```bash
@@ -156,8 +174,8 @@ not found, so `allFound` is `false`.
 
 ### commandName
 
-The name of the executable to locate. On Windows, the function automatically checks for
-common executable extensions (.exe, .cmd, .bat, .ps1, etc.) if no extension is provided.
+The name of the executable to locate. On Windows, it automatically checks for common executable  
+extensions, like `.exe`, `.cmd`, and `.bat`, if no extension is provided.
 
 ```yaml
 Type:     string
@@ -176,20 +194,22 @@ Type: string or null
 
 ## Error conditions
 
-The function returns `null` instead of generating errors when the executable is not found.
-It will return an error only if:
+The function returns `null` instead of generating errors when the executable isn't found.  
 
-- **Not a string**: The input is not a string (e.g., number, array, object, null)
+The function only returns an error when the input isn't a string.
 
 ## Notes
 
-- The function searches the PATH environment variable in the same order as the operating system
-- On Windows, common executable extensions are automatically checked (.exe, .cmd, .bat, .ps1, etc.)
-- Returns `null` (not an error) when the executable is not found
-- The returned path is always absolute
-- Use with [`if()`][00] or [`coalesce()`][01] for conditional logic based on tool availability
-- The search is case-insensitive on Windows and case-sensitive on Unix-like systems
-- Symbolic links are resolved to their target paths
+- The function searches the `PATH` environment variable in the same order as the operating system.  
+- On Windows, the function automatically checks for the executable with common extensions, like  
+  `.exe`, `.cmd`, and `.bat`, when the input string doesn't define an extension. For example, if  
+  the input is `dsc`, the function would return `dsc.exe` if available in `PATH`.  
+- The function returns `null` when the executable isn't found instead of raising an error.  
+- The function always returns the absolute path to a discovered executable.  
+- Use with [`if()`][00] or [`coalesce()`][01] for conditional logic based on tool availability.  
+- The function searches for the executable case-insensitively on Windows and case-sensitively on  
+  other platforms.  
+- The function resolves symbolic links to their target paths.
 
 ## Related functions