Merge remote-tracking branch 'upstream/main' into stage0/interfaces-data-structures

# Conflicts:
#	examples/stage0/snippets/src/Loops.java
#	src/content/docs/learning-course/stage0/loops.mdx

Author: zachwaffle4

examples/stage0/snippets/src/Loops.java

@@ -29,10 +29,15 @@ void main() {
     }
 
     // [whileExample2]
-    int autoTimer = 0;
-    while (autoTimer <= 15){
-        System.out.println("AutoMode is happening");
-        autoTimer++;
+    int timer = 0;
+
+    while (timer <= 5) {
+      if (timer < 5) {
+        System.out.println("Drive Forward");
+      } else {
+        System.out.println("Stop Driving");
+      }
+      timer++;
     }
     // [/whileExample2]
 
@@ -53,29 +58,9 @@ void main() {
     }
     //[/ForExample2]
 
-    //
     // [forExample]
     for (int i = 0; i < 5; i++){
         System.out.println(i); // prints 0, 1, 2, 3, 4
     }
     // [/forExample]
-
-    if (false) {
-        // [Infinite1]
-        int timer = 0;
-        while (timer < 7){
-            drivetrain.setThrottle(1); // sets drive motors to full speed
-        }
-        // [/Infinite1]
-    }
-
-    {
-        // [Infinite2]
-        int timer = 0;
-        while (timer < 7) {
-            drivetrain.setThrottle(1); // sets drive motors to full speed
-            timer++; // increments timer by 1
-        }
-        // [/Infinite2]
-    }
-}
+}

src/content/docs/learning-course/stage0/loops.mdx

@@ -7,62 +7,58 @@ codeRegionSources:
     default: stage0/snippets/src/Loops.java
 ---
 
-Oftentimes we want to do the same action multiple times in a row.
+Oftentimes in code, there is a need to repeat the same action multiple times in a row.
 For instance, if you know your grades are about to be released, you might repeatedly check them until they come out.
 In Java we can use loops to do this.
 
-We will be going over two types of loops which are:
-
-- while
-- for
+In this lesson, we're going to cover two main types of loops: **while** loops and **for** loops.
 
 <Aside type="note">
-    There is another type of loop called do while and because it's not commonly
-    used in FRC we will not be covering it. However, if you want to learn more
+    There is another type of loop, the do-while loop. We will not be covering it
+    because it isn't commonly used in FRC. However, if you want to learn more
     about do while loops, you can learn more on w3school's page on [do while
     loops](https://www.w3schools.com/java/java_while_loop_do.asp)
 </Aside>
 
 Conditionals and loops may seem similar but they have different purposes.
-Conditionals are used to make decisions based on whether the condition is true or false.
-Loops are used to repeat code until the condition is met.
-This can be thought of conditionals make decisions, and loops are for repeating.
+Conditionals and loops both control the flow of programs.
+Conditionals are used to run a block of code once, whereas a loop can run a block of multiple times
 
 ## while
 
 `while` loops are the most simple type of loops.
-If you have used block coding before, this is similar to the repeat block.
-If you have taken an CS class, you might already be familiar with a `while` loop.
 
 The syntax of a `while` loops is as shown:
 
 ```java #whileSyntax
 
 ```
 
-You might notice that a `while` loop has a similar syntax to conditionals, which was discussed in the previous section.
-A `while` loop's syntax includes:
+You might notice that a `while` loop looks very similar to the `if` conditional, which was discussed in the previous lesson.
+A `while` loop includes:
 
-- `while` is a keyword
-- `( )` holds the condition that is either true or false.
+- the `while` keyword to declare that we're making a `while` loop
+- `( )` to hold the condition that is either true or false.
   Example: (5 > 1) is a condition and it is true because 5 is greater than 1
-- `{` an open bracket is used to denote the opening of the loop
-- `}` a closed bracket is used to denote the end of the loop
+- `{` to denote the opening of the loop's code block
+- `}` to denote the end of the loop's code block
 
-Another way of understanding how a `while` loop works is with the flow chart below
+The following flowchart demonstrates how a while loop works:
 
 <ContentFigure
     src="/learning-course/stage0/loops/WhileLoop.webp"
     width="300px"
     height="300px"
 />
 
-Similar to conditionals, a `while` loop will run the code block inside the `while` loop when the condition is true.
-After the code block is run, it goes back to the condition.
-If the condition is true, the code block will run again.
+Like the `if` conditional, the `while` loop will run its code block if the condition is true.
+Unlike the `if` conditional, however, when the code block is done, the `while` loop will evaluate its condition again.
+If the condition is still true, the code block will run again.
 This will repeat until the condition is false.
-When it's false, the loop will be skipped.
-To understand how this works, let's look at an example.
+Also unlike the `if` conditional, a `while` loop (or any other type of loop) can't have any `else` statements attached.
+This means that if the condition is false when the loop is first encountered, the entire thing is skipped.
+
+Let's look at an example:
 
 ```java #whileExample
 
@@ -74,7 +70,7 @@ We know that 0 is less than 6 so the `while` code block runs and the value of `i
 The value of `i` is also updated because of `i++` and it changes to 1.
 Now the condition checks if 1 is less than 6. We know that it is true, so the value of `i` gets printed and the value of `i` is increased by 1.
 This repeats and eventually `i`'s value becomes 6.
-6 is not less than 6, therefore the loop is done and the `while` code block does not run.
+Now, when the condition is evaluated, it's `false`, as 6 is not less than 6, so the loop is complete.
 
 <Aside type="tip">
     Does the ``i++`` look familiar? This was covered in the operator section. If
@@ -91,11 +87,20 @@ In the example below we have:
 
 Without running the code, what do you think happens?
 
-`autoTimer` is set to 0. The `while` loop's condition is `autoTimer <= 15`.
-0 is less than 15 so the code enters the `while` code block, and prints outs `Auto is happening`.
-`autoTimer++` is run which increases `autoTimer`'s value by one.
-The code goes back to the condition, 1 is less than 15, so the code enters the `while` code block again, printing out `Auto is happening`.
-Like before, `autoTimer++` runs which increases `autoTimer` by one again making the value be 2. This repeats until `autoTimer` is 16. When that happens the condition is false and the `while` loop is skipped.
+`timer` is set to 0, and the `while` loop’s condition is checking if `timer` is less than or equal to 5.
+0 is less than 5, so the code enters the while loop.
+Now the `if` statement checks whether `timer` is less than 5.
+0 is less than 5, so it prints out `Drive Forward`.
+The `if` statement is done, and the code runs `timer++`, which increases `timer`’s value by one.
+
+The code goes back to the `while` loop.
+1 is less than 5, so the code enters the `while` loop again.
+For the `if` statement, 1 is less than 5.
+Therefore, `Drive Forward` gets printed out again.
+
+This repeats 4 times until `timer` is 5.
+Once this happens, the `if` statement is skipped since 5 is not less than 5.
+Now the else runs and prints out `Stop Driving`, `timer`’s value increases to 6, 6 is not less than 5, so the code stops running.
 
 ## for
 
@@ -113,23 +118,26 @@ For loops allow us to inline these statements:
 
 ```
 
-Using the example above, we can see that the `for` loop syntax goes as follows:
+Using the previous example, we can see that the `for` loop syntax includes:
 
-- `for` is a keyword
-- `()` holds the three statements
-- `{` an open bracket is used to denote the opening of the loop
-- `}` a closed bracket is used to denote the end of the loop
+- the `for` keyword to declare that we're making a `for` loop
+- `()`to hold the three statements which allow the loop to run
+- `{` to denote the opening of the loop's code block
+- `}` to denote the ending of the loop's code block
 
 The three statements are
 
 - **initialization**: creates a variable that sets the starting point of the loop.
-  This is the `int i = 0;` seen in the example above.
+  This is the `int i = 0;` seen in the previous example.
 - **condition**: a condition, which uses the variable, that is checked before each iteration.
   This is `i < 6;`.
   If the condition is true, the code inside the loop runs
 - **update**: updates the variable created in initialization after each iteration.
   Lastly, that's `i++`;
 
+All 3 statements are optional, but the semicolons must be present.
+However, the examples in this section will use all statements.
+
 Let's look at another example:
 
 ```java #forExample
@@ -145,6 +153,9 @@ When `i` is no longer less than 5, the `for` loop is skipped.
 
 It is important to make sure that the condition can become false.
 If the condition is always true, the loop will always run causing an infinite loop.
+When an infinite loop happens, the code never stops.
+This can be unsafe if the code is running a robot mechanism.
+This could cause a robot to never stop driving forward or an arm to always move.
 Infinite loops can be prevented by ensuring that the value inside the condition changes by incrementing or decrementing.
 
 <Aside type="note">
@@ -154,8 +165,15 @@ This will be talked about more in Stage 1
 
 </Aside>
 
-```java #Infinite1
+{/* rli:ignore */}
 
+```java
+    int timer = 0;
+    if (false) {
+        while (timer < 7){
+            drivetrain.setThrottle(1); // sets drive motors to full speed
+        }
+    }
 ```
 
 In this example, we want our drive train to run for 7 seconds.
@@ -166,8 +184,14 @@ This means `timer` will always be 0. 0 is less than 7 so the loop will continuou
 
 To fix this, we would make sure to increment the timer value as shown below.
 
-```java #Infinite2
+{/* rli:ignore */}
 
+```java
+    int timer = 0;
+    while (timer < 7){
+        drivetrain.setThrottle(1); // sets drive motors to full speed
+        timer++; // increments timer by 1
+    }
 ```
 
 `timer` now increments by 1 each time the loop is run, and the robot will stop driving after 7 seconds.