Merge pull request #2 from Team2537/better-mathew

Suggestions and Semantics

book/book.toml

@@ -1,5 +1,5 @@
 [book]
-authors = ["Matthew", "Falon"]
+authors = ["Matthew E.", "Falon", "Matthew C."]
 language = "en"
 multilingual = false
 src = "src"

book/src/kotlin/unit-1/1-1.md

@@ -29,6 +29,8 @@ number = 20 // Will not cause an error
 println(number) // Output: 20
 ```
 
+<!-- The concept of comments and their syntax should probably be somewhere in here - better Matthew -->
+
 In the example above, we declare a variable `number` of type `Int` and assign it a value of `10`. We then print the
 value of `number`, which is `10`. Next, we assign a new value of `20` to `number`, and print the value of `number`,
 which is now `20`.
@@ -62,15 +64,12 @@ common data types supported by Kotlin:
 | Data Type | Description                     |
 |-----------|---------------------------------|
 | `Int`     | Whole number, no decimal places |
-| `Double`  | Number with decimal places      |
-| `Float`   | Number with decimal places      |
+| `Double`  | Number with ~15 decimal places  |
+| `Float`   | Number with ~7 decimal places   |
 | `Boolean` | `true` or `false`               |
 | `Char`    | Single character                |
 | `String`  | Sequence of characters          |
 
-The difference between `Double` and `Float` is the amount of memory used, this means that double can store more decimal
-places than float.
-
 ### Example
 
 ```kotlin
@@ -84,8 +83,10 @@ var height: Int = "Five Feet" // Causes an error because the data type is incorr
 var weight = 150 // Kotlin can infer the data type, so you don't need to specify it
 ```
 
-When possible, even though Kotlin can infer the data type, it is recommended to specify the data type to avoid any
-confusion.
+### Type Inference
+
+When a variable is given a value immediately, with its declaration, the type of the variable will automatically be
+chosen, or inferred. However, it is often recommended to specify the data type to avoid confusion.
 
 ### Nullability
 
@@ -197,8 +198,8 @@ println(x > y || x == 5) // Output: true
 ## String Formatting
 
 Although not an operator, string formatting is a useful technique for combining strings and variables. In Kotlin, you
-can use string templates to insert variables into strings. To use a string template, you enclose the variable name in
-curly braces `{}` within a string.
+can use string interpolation to insert variables into strings. To use string interpolation, prefix the variable name
+with a dollar sign (`$`). You may also enclose the variable name with curly-braces (e.g. `${myVar}`).
 
 ### Example
 

book/src/kotlin/unit-1/1-2.md

@@ -150,13 +150,13 @@ You can create a range of numbers by specifying the start and end values separat
 includes the start value and the end value.
 
 ```kotlin
-val range = 1..5 // 1, 2, 3, 4, 5
+val range = 1..5 // {1, 2, 3, 4, 5}
 ```
 
 You can also create a range that counts down by using the `downTo` keyword.
 
 ```kotlin
-val range = 5 downTo 1 // 5, 4, 3, 2, 1
+val range = 5 downTo 1 // {5, 4, 3, 2, 1}
 ```
 
 ### Collections

book/src/kotlin/unit-1/1-3.md

@@ -34,6 +34,28 @@ In the example above, we define a function `add` that takes two parameters `a` a
 sum. We then call the function with arguments `5` and `3` and store the result in a variable `sum`. Finally, we print
 the value of `sum`, which is `8`.
 
+<!-- Moved this up here, as a void function was used in an example before its explanation
+    Personally, I think it should have started by explaining void functions, then showed returning functions,
+    but I'm not the lead here so eh whatever - better Matthew -->
+Functions often return a value using the `return` keyword, but not all of them do. If a function does not return a
+value, it has a return type of `Unit`. `Unit` is similar to `void` in other languages and indicates that the function 
+does not return anything. Such functions are often used to perform repetitive and common tasks,
+such as outputting text with `println()`.
+
+### Example
+
+```kotlin
+fun greet(name: String) { // Return type is Unit, no need to specify
+    println("Hello, $name!")
+}
+
+greet("Alice") // Output: Hello, Alice!
+```
+
+In the example above, we define a function `greet` that takes a parameter `name` of type `String` and prints a greeting
+message. The return type of the function is `Unit`, which is not explicitly specified. 
+For the sake of conciseness, `Unit` is almost always omitted as a return type.
+
 You can also define functions with default values for parameters. This allows you to call the function without providing
 values for all parameters. If you do not provide a value for a parameter with a default value, the default value will be
 used.
@@ -75,24 +97,6 @@ In the example above, we define a function `greet` with two parameters `greeting
 with default values of `"Hello"` and `"World"`, respectively. We then call the function with different combinations of
 arguments and named arguments to see how the default values are used.
 
-Functions often return a value using the `return` keyword. If a function does not return a value, you can specify the
-return type as `Unit`. `Unit` is similar to `void` in other languages and indicates that the function does not return
-anything.
-You can omit the return type if the function does not return anything. The return type will default to `Unit`.
-
-### Example
-
-```kotlin
-fun greet(name: String) { // Return type is Unit, no need to specify
-    println("Hello, $name!")
-}
-
-greet("Alice") // Output: Hello, Alice!
-```
-
-In the example above, we define a function `greet` that takes a parameter `name` of type `String` and prints a greeting
-message. The return type of the function is `Unit`, which is not explicitly specified.
-
 Functions can also be defined as expressions using the `=` operator. This allows you to define functions concisely
 without using curly braces and the `return` keyword.
 

book/src/kotlin/unit-1/1-5.md

@@ -55,9 +55,12 @@ class Person(val name: String, val age: Int) {
 So now we can access the `name` and `age` properties outside of the `init` block. Here is an example of creating a
 `Person` object with a name and age:
 
+<!-- Where the side effects intentionally left out here? -still better Matthew -->
+
 ```kotlin
 fun main() {
-    val person = Person("Alice", 30)
+    val person = Person("Alice", 30) // Output: Name: Alice
+                                     //         Age: 30
     println(person.name) // Output: Alice
     println(person.age) // Output: 30
 }