Refactor Introduction Koans (#370)

* ♻️ 📝 update AboutAssertions

* ♻️ 🎨 Refactor AboutBinary

* 📝 Refactor AboutBooleans intro text

* 📝 first pass of AboutArrays

* ♻️ 🎨 Refactor AboutStrings

* ♻️ 🎨 ✨ AboutNumbers
- Some refactoring and rewriting of comments.
- Added mention of suffixes and Long type.

Author: vexx32

PSKoans/Koans/Foundations/AboutArrays.Koans.ps1

@@ -4,51 +4,60 @@ param()
 <#
     Arrays and Iterable Collections
 
-    Like many programming languages, PowerShell often uses arrays to keep collections
-    of objects together. Arrays tie in closely with PowerShell's pipeline, which
-    is one way to iterate over a collection with a good deal of efficiency.
+    Like many programming languages, PowerShell often uses arrays to keep
+    collections of objects together. Arrays tie in closely with PowerShell's
+    pipeline, which is one way to iterate over a collection with a good deal of
+    efficiency.
 
     There are a few 'array-like' collection types available in PowerShell, all
-    of which are rooted in .NET classes and data types, and behave much the
-    same as they do in C# and VB.NET.
+    of which are rooted in .NET classes and data types, and behave much the same
+    as they do in other .NET languages.
 
-    Arrays in particular have a close relationship with the PowerShell pipeline,
-    which will be covered a shortly.
+    Arrays in particular are closely tied to the PowerShell pipeline, which are
+    covered in another topic.
 #>
 Describe 'Arrays' {
 
     It 'is useful for grouping related objects and values' {
-        # The comma operator is used to create an array. Spaces are typically ignored.
+        <#
+            The comma operator is used to create an array.
+            Spaces are typically ignored.
+        #>
         $Ages = 12, 25, 18, 64
 
         <#
-            Individual elements of an array can be accessed with square-bracket index syntax.
-            Arrays are zero-indexed; the first element is at index 0, the second at 1, etc.
+            Individual elements of an array can be accessed with square-bracket
+            index syntax. Arrays are zero-indexed; the first element is at index
+            [0], the second at [1], etc.
         #>
         $Ages[0] | Should -Be 12
         __ | Should -Be $Ages[3]
     }
 
     It 'can be created with the @() operator' {
         <#
-            The array subexpression operator @() is used to create an array from multiple values
-            or expressions. Within the parentheses, you can use commas, semicolons, and even line
-            breaks to divide array elements.
+            The array subexpression operator @() is used to create an array
+            from multiple values or expressions. Within the parentheses, you can
+            use commas, semicolons, or even line breaks to divide each element.
         #>
         $Names = @(
             'Steve'
             'John'; 'Jaime' # This is a messy way to do things, but it does work
             'Abigail', 'Serena', 'Kali'
-            # Having everything on its own line would be much cleaner and is a common usage of this syntax.
+            <#
+                Having everything on its own line would be much cleaner and is a
+                more common usage of this syntax.
+            #>
         )
 
         # Where is index 4 in the above array?
         __ | Should -Be $Names[4]
 
         <#
-            Although in many cases in PowerShell, an expression that only returns one value will
-            not become an array, this operator forces the value or object to be wrapped in an array
-            if the result is not already an array; it guarantes the result will be an array.
+            Although in many cases in PowerShell, an expression that only
+            returns one value will not become an array, this operator forces the
+            value or object to be wrapped in an array if the result is not
+            already an array; it guarantes the result will be an array.
         #>
         $Array = @( 10 )
 
@@ -66,28 +75,32 @@ Describe 'Arrays' {
 
     It 'can be created using the addition operator' {
         <#
-            To add an element to a fixed size array, a new array must be created. PowerShell does this
-            in the background when the addition operator is used.
+            To add an element to a fixed size array, a new array must be
+            created. PowerShell does this in the background when the addition
+            operator is used.
         #>
 
         $Ages = 12, 25, 18, 64
 
         $Age = __
         $Ages = $Ages + $Age
 
-        # The operation above can be shortened using the Add-and-Assign operator.
+        <#
+            The operation above can be shortened using the addition and
+            assignment combination operator.
+        #>
 
         $Age = __
         $Ages += $Age
 
         $Ages | Should -Be 12, 25, 18, 64, 42, 59
 
         <#
-            The cost of adding an element to an array in PowerShell like this increases with the
-            size of the array.
+            The cost of adding an element to an array in PowerShell like this
+            increases with the size of the array.
 
-            Each time a new element is added, the array must be copied to a new larger array to accommodate
-            the new values.
+            Each time a new element is added, the array must be copied to a new
+            larger array to accommodate the new values.
 
             The result of the operation is another fixed size array.
         #>
@@ -120,10 +133,11 @@ Describe 'Arrays' {
         __ | Should -Be $Others
 
         <#
-            If you know the contents of the array and want to skip specific elements, you can
-            assign specific elements to $null to discard them. $null is one of PowerShell's
-            automatic variable values, like $true and $false, and cannot be altered. Any data
-            you attempt to assign to it will be ignored.
+            If you know the contents of the array and want to skip specific
+            elements, you can assign specific elements to $null to discard them.
+            $null is one of PowerShell's automatic variable values, like $true
+            and $false, and cannot be altered. Any data you attempt to assign to
+            it will be ignored.
         #>
         $null, $Number1, $Number2 = $Others
         __ | Should -Be $Number1
@@ -164,7 +178,7 @@ Describe 'Arrays' {
 
         $List.Count | Should -Be $Array.Count
 
-        # The List collection used above is covered in more detail in a later Koan.
+        # The List collection used above will be explored more in a later topic.
     }
 
     It 'allows use of negative indexes' {
@@ -177,9 +191,10 @@ Describe 'Arrays' {
 
         $Index = __
         $Array[-3, $Index, -6] | Should -Be @(5, 1, 2)
+    }
 
-        # You can make use of this to reverse an entire array
-        $LastIndex = __ # Hint: needs to be a negative number!
+    It 'can reverse an array' {
+        $LastIndex = __
         $Array[-1..$LastIndex] | Should -Be @(7, 6, 5, 4, 3, 2, 1)
     }
 
@@ -192,11 +207,16 @@ Describe 'Arrays' {
         # What about undefined negative indexes?
         __ | Should -Be $Array[-10]
 
-        # NOTE: The above will actually throw errors if you have PowerShell running in Strict Mode.
+        <#
+            📝 NOTE
+
+            The above will actually throw errors if you have PowerShell
+            running in Strict Mode.
+        #>
     }
 
     It 'can create be created from a range' {
-        # The .. notation used to reverse an array may be used to array.
+        # The .. notation used to reverse an array can be used to copy an array.
 
         $Array = 1, 2, 3, 4, 5
 
@@ -209,26 +229,41 @@ Describe 'Arrays' {
         $lastLetter = '__'
 
         if ($PSVersionTable.PSEdition -eq 'Core') {
-            # PowerShell Core uses .. between the letters to create an array.
+            # PowerShell 6.2+ can use .. between the letters to create an array.
 
             $letters = $firstLetter..$lastLetter
 
             $letters | Should -Be 'a', 'b', 'c', 'd'
         }
         else {
-            # Windows PowerShell 5 and below have to work a lot harder to achieve the same thing.
+            <#
+                Windows PowerShell 5 and below have to work a lot harder to
+                achieve the same thing.
+            #>
 
-            $letters = ([Int][Char]$firstLetter)..([Int][Char]$lastLetter) -as [Char[]]
+            $startIndex = [Int][Char]$firstLetter
+            $endIndex = [Int][Char]$lastLetter
+            $letters = ($startIndex)..($endIndex) -as [char[]]
 
             $letters | Should -Be 'a', 'b', 'c', 'd'
         }
     }
 
     It 'is usually of type Object[]' {
         <#
-            Arrays in PowerShell are created with the type Object[]. An array of Objects.
-
-            The Object type can hold anything at all. A numeric value, a character, a Process, and so on.
+            Arrays in PowerShell are created with the type Object[]. Object is
+            the parent type of all .NET objects, and the [] suffix denotes that
+            the type represents an array containing multiple items of that type.
+            You may also occasionally see things like int[,] which denotes a two
+            dimensional array containing integers.
+
+            In .NET, a child type can be "boxed" into its parent type and be
+            treated the same (think of it like a child type being an add-on to
+            the parent type; you can always cut away the additions and just work
+            with the parent type if you really need to). Object is the sole
+            parent type for all .NET objects, regardless of their type. As such,
+            an array of type Object[] effectively has no restrictions on what
+            can be inserted into one of its slots.
         #>
 
         $Numbers = 1, 2, 3, 4
@@ -241,11 +276,12 @@ Describe 'Arrays' {
         '____' | Should -Be $Processes.GetType().Name
 
         <#
-            The base type of Object[], Char[], and other fixed size array types is the System.Array
-            type, or [Array].
+            The base type of Object[], Char[], and other fixed size array types
+            is the System.Array type, or [Array].
 
-            The [Array] type describes the Length property (which is also aliased to Count in PowerShell),
-            as well as other methods which can be used to work with the array.
+            The [Array] type describes the Length property (which is also
+            aliased to Count in PowerShell), as well as other methods which can
+            be used to work with the array.
         #>
     }
 

PSKoans/Koans/Introduction/AboutAssertions.Koans.ps1

@@ -5,20 +5,21 @@ param()
     Getting Started
 
     The PowerShell Koans are a set of exercises designed to get you familiar
-    with PowerShell. By the time you're done, you'll have a basic
-    understanding of the syntax of PoSH and learn a little more
-    about scripting in general.
-
-    Answering Problems
-
-    This is where the fun begins! Each koan contains an example designed
-    to teach you a lesson about PowerShell. If you execute the program
-    defined in this project, you will get a message that the koan below
-    has failed. Your job is to fill in the blanks (the __ or ____ symbols)
-    to make it pass. Once you make the change, call Show-Karma to make sure
-    the koan passes, and continue on to the next failing koan.
-    With each passing koan, you'll learn more about PowerShell, and add
-    another tool to your PowerShell scripting belt.
+    with PowerShell. By the time you're done, you'll have a basic understanding
+    of the syntax of PowerShell and learn a little more about scripting. This is
+    where the fun begins! Each koan contains an example designed to teach you
+    something about PowerShell.
+
+    Solving Problems
+
+    If you execute the `Show-Karma` command in your PowerShell console, you will
+    get a message that one of the assertions below has failed. Your job is to
+    fill in the blanks (the __ / ____ / $____ / '____' tokens) to make it pass.
+
+    Once you make the change(s) necessary and save the file, call `Show-Karma`
+    to make sure the koan passes, and continue on to the next failing koan. With
+    each passing koan, you'll learn more about PowerShell, and add another tool
+    to your PowerShell scripting belt.
 #>
 Describe 'Equality' {