docs: rewrite descriptions

Author: danielzting

levels/bubble_sort.gd

@@ -2,11 +2,16 @@
 BUBBLE SORT
 
 
-Bubble sort iterates through the array and looks at each pair of
-elements, swapping them if they are out of order. When it has gone
-through the entire array without swapping a single pair, it has
-finished. Though simple to understand, bubble sort is hopelessly
-inefficient on all but the smallest of arrays.
+Bubble sort looks at consecutive pairs of elements and swaps them if
+they are out of order, finishing when it has gone through the whole
+array from beginning to end without a single swap. The actual level
+contains an optimization that skips over elements guaranteed to be
+already in place.
+
+Due to its simplicity, it is commonly taught as the first sorting
+algorithm students learn in computer science classes, but is rarely used
+in real life because it is slow on large data and other simple quadratic
+algorithms like insertion sort perform better.
 
 
 If the two highlighted elements are out of order, hit LEFT ARROW to swap

levels/cocktail_sort.gd

@@ -2,8 +2,12 @@
 COCKTAIL SORT
 
 
-Cocktail shaker sort is a variation of bubble sort that
-alternates going backwards and forwards.
+Cocktail sort is a variation of bubble sort that alternates going
+backwards and forwards. The actual level contains an optimization that
+skips over elements guaranteed to be already in place.
+
+Because it is bidirectional, it is slightly faster than bubble sort, but
+is still quadratic and therefore not used on large data.
 
 
 If the two highlighted elements are out of order, hit LEFT ARROW to swap
@@ -22,10 +26,8 @@ def cocktail_sort(a):
             if array[i] > array[i + 1]:
                 a.swap(i, i + 1)
                 swapped = true
-
         if not swapped:
             break
-
         swapped = false
         for i in range(len(a) - 1, 0, -1)
             if a[i - 1] > a[i]:

levels/comb_sort.gd

@@ -2,7 +2,14 @@
 COMB SORT
 
 
-Comb sort is a variant of bubble sort that operates on gapped arrays.
+Comb sort is a variant of bubble sort that compares elements a certain
+gap apart instead of consecutive elements. This gap is divided after
+every pass by an experimentally determined optimal factor of about 1.3.
+Once the gap becomes 1, comb sort becomes a regular bubble sort.
+
+This allows comb sort to get rid of small values near the end more
+quickly, which turns out to be the bottleneck in bubble sort, but still
+has a quadratic worst case.
 
 
 If the two highlighted elements are out of order, hit LEFT ARROW to swap
@@ -17,6 +24,7 @@ def comb_sort(a):
     gap = len(a)
     swapped = true
     while gap != 1 or swapped:
+        swapped = false
         gap = max(gap / 1.3, 1)
         for i in range(len(a) - gap):
             if a[i] > a[i + gap]:

levels/comparison_sort.gd

@@ -12,8 +12,8 @@ const EFFECTS = {
 
 const DISABLE_TIME = 1.0
 var NAME = _get_header().split("   ")[0]
-var DESCRIPTION = _get_header().split("   ")[1]
-var CONTROLS = _get_header().split("   ")[2]
+var DESCRIPTION = _get_header().split("   ")[1].replace("  ", "\n\n")
+var CONTROLS = _get_header().split("   ")[-1]
 
 var array: ArrayModel
 

levels/cycle_sort.gd

@@ -2,13 +2,20 @@
 CYCLE SORT
 
 
-Cycle sort repeatedly counts the number of elements less than the first
-and swaps it with that index until the smallest element is reached. Then
-it does this process starting at the next out-of-place element.
+Cycle sort looks at the first element and finds its correct final
+position by counting the number of elements smaller than it. Then it
+saves the element at that index, writes the first element there, and
+repeats the process with the saved element. For the sake of
+demonstration, in the actual level, swaps are used instead.
 
+This results in a quadratic runtime but gives it the special property
+of being optimal in the number of writes to the array. This makes cycle
+sort useful in storage types where writes are very expensive or reduce
+its lifespan.
 
-If the highlighted element is less than the pointer, hit LEFT ARROW.
-Otherwise, hit RIGHT ARROW.
+
+If the highlighted element is less than the element below the blue
+pointer, hit LEFT ARROW. Otherwise, hit RIGHT ARROW.
 """
 
 class_name CycleSort

levels/insertion_sort.gd

@@ -2,16 +2,17 @@
 INSERTION SORT
 
 
-Insertion sort goes through the array and inserts each
-element into its correct position. It is most similar to how most people
-would sort a deck of cards. It is also slow on large arrays but it is
-one of the faster quadratic algorithms. It is often used to sort smaller
-subarrays in hybrid sorting algorithms.
+Insertion sort goes through the array and inserts each element into its
+correct place, like how most people would sort a hand of playing cards.
 
+It is one of the fastest quadratic algorithms in practice and is
+efficient on small or almost sorted data. It is also simple, stable, and
+in-place. For these reasons it is sometimes used within faster divide
+and conquer algorithms when the array has been divided to a small size.
 
-Hit LEFT ARROW to swap the two highlighted elements as long as they are
-out of order. When this is no longer the case, hit RIGHT ARROW to
-advance.
+
+If the two highlighted elements are out of order, hit LEFT ARROW to swap
+them. Otherwise, hit RIGHT ARROW to continue.
 """
 
 class_name InsertionSort

levels/merge_sort.gd

@@ -2,16 +2,15 @@
 MERGE SORT
 
 
-Merge sort is an efficient sorting algorithm that splits the array into
-single-element chunks. Then it merges each pair of chunks until only one
-sorted chunk is left by repeatedly choosing the smaller element at the
-head of each chunk and moving the head back. However, it needs an entire
-array's worth of auxiliary memory.
+Merge sort merges subarrays of increasing size by setting a pointer to
+the head of each half. Then it repeatedly copies the smaller pointed
+element and increments that side's pointer. When one side is exhausted,
+it copies the rest of the other side and overwrites the two halves with
+the merged copy.
 
 
 Press the ARROW KEY corresponding to the side that the smaller
-highlighted element is on. If you've reached the end of one side, press
-the other side's ARROW KEY.
+highlighted element is on or the non-exhausted side.
 """
 
 class_name MergeSort
@@ -34,6 +33,7 @@ def merge_sort(a):
                     merged.append(a[i])
                     i += 1
             a[begin:begin + size] = merged
+        size *= 2
 """
 const ACTIONS = {
     "LEFT": "Left",

levels/odd_even_sort.gd

@@ -2,8 +2,12 @@
 ODD-EVEN SORT
 
 
-Odd-even sort is a variant of bubble sort that alternates on elements at
-odd and even indices.
+Odd-even sort is a variant of bubble sort that alternates between
+comparing consecutive odd-even and even-odd indexed pairs.
+
+It is not of much use on a single processor as it is designed for
+parallel processors, which can perform every comparison in a single pass
+at the same time, thus making the algorithm much more efficient.
 
 
 If the two highlighted elements are out of order, hit LEFT ARROW to swap

levels/quick_sort.gd

@@ -2,18 +2,19 @@
 QUICKSORT
 
 
-Quicksort designates the last element as the pivot and puts everything
-less than the pivot before it and everything greater after it. This
-partitioning is done by iterating through the array while keeping track
-of a pointer initially set to the first element. Every time an element
-less than the pivot is encountered, it is swapped with the pointed
-element and the pointer moves forward. At the end, the pointer and pivot
-are swapped, and the process is repeated on the left and right halves.
+Quicksort designates the last element as the pivot and sets a pointer to
+the first element. Then it iterates through the array. Every time an
+element smaller than the pivot is encountered, that element is swapped
+with the pointed element and the pointer is incremented. Once the pivot
+is reached, it is swapped with the pointed element and this process is
+recursively repeated on the left and right halves.
+
+Quicksort competes with other linearithmic algorithms like merge sort,
+which it is faster than at the tradeoff of stability.
 
 
 If the highlighted element is less than the pivot or the pivot has been
-reached, press LEFT ARROW to swap it with the pointer. Otherwise, press
-RIGHT ARROW to move on.
+reached, press LEFT ARROW. Otherwise, press RIGHT ARROW.
 """
 
 class_name QuickSort

levels/selection_sort.gd

@@ -2,16 +2,16 @@
 SELECTION SORT
 
 
-Selection sort incrementally builds a sorted array by repeatedly looking
-for the smallest element and swapping it onto the end of the sorted
-portion of the array, which initially starts with size zero but grows
-after each round. It is faster than an unoptimized bubble sort but
-slower than insertion sort.
+Selection sort incrementally builds a sorted subarray by finding the
+smallest unprocessed element and putting it in place.
 
+It is not very useful in real life as it is beat by insertion sort.
+However, it has the distinguishing feature of making the least number
+of swaps in the worst case.
 
-Keep on hitting RIGHT ARROW until you encounter an element that is
-smaller than the left highlighted element, then hit LEFT ARROW and
-repeat.
+
+If the two highlighted elements are out of order, hit LEFT ARROW to swap
+them. Otherwise, hit RIGHT ARROW to continue.
 """
 
 

levels/shell_sort.gd

@@ -2,13 +2,18 @@
 SHELL SORT
 
 
-Shell sort is a variation of insertion sort that sorts arrays separated
-by gaps.
+Shell sort is a variant of insertion sort that compares elements a
+certain gap apart instead of consecutive elements. This gap is divided
+by 2 after every pass. Once the gap becomes 1, shell sort becomes a
+regular insertion sort.
 
+This allows the final pass of insertion sort to avoid having to move
+elements long distances. However, it still has a quadratic worst case,
+which can be reduced with more complex gap sequences.
 
-Hit LEFT ARROW to swap the two highlighted elements as long as they are
-out of order. When this is no longer the case, hit RIGHT ARROW to
-advance.
+
+If the two highlighted elements are out of order, hit LEFT ARROW to swap
+them. Otherwise, hit RIGHT ARROW to continue.
 """
 
 class_name ShellSort

scenes/levels.tscn

@@ -71,7 +71,9 @@ margin_top = 20.0
 margin_right = 596.0
 margin_bottom = 593.0
 size_flags_vertical = 3
-text = "This is a description for the level in the form of psuedocode.
+text = "This is a description of the algorithm in plain English.
+
+This explains the relevance of the algorithm in computer science.
 
 def algorithm(parameter):
     return result"